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Introduction 


All programs interface with the 68xxx UniFLEX Operating System 
( UniFLEX Registered in U.S. Patent and Trademark Office) through 
system calls. The operating system supports a variety of calls, which 
allow the manipulation of files, the control of tasks, and other system 
functions. The assemblers have a built-in instruction, "sys", to make 
system calls to the operating system. The syntax for this system call 
follows: . * 
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J lb sys$&T 

sys <function__code> [<param__list> ] 
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where <f unction_code> is a 16-bit code for the desired system call (the 
file "/lib/sysdef 11 defines the correspondence between function codes and 
system calls). The number and type of parameters in the list may range 
from 0 to 4 inclusive. The parameters are always 32-bit values. 


Many of the system calls expect certain values or parameters to be in 
one or more of the 68xxx CPU's registers. The documentation for a 
system call shows any such items in the section entitled ASSEMBLY 
LANGUAGE SYNTAX under the subheading "Expected”. In such cases it is 
the programmer's responsibility to load the proper values before 
invoking the system call. 


When the "sys" instruction completes execution, control generally passes 
to the next instruction in the program. In some cases the system call 
must return one or more values to the calling program. Generally, a 
system call places such a value in a register although in some cases, it 
places it in a location specified in <param__list>. The documentation 
for a system call shows any values returned in a register in the section 
entitled ASSEMBLY LANGUAGE SYNTAX under the subheading "Returns". 


The operating system preserves all registers throughout the execution of 
a successful system call unless the system call returns a value in a 
register. If the system call fails, the call always returns the error 
number of the error that caused the failure in the DO register. 


The operating system also preserves all condition codes throughout a 
system call with the exception of the error (or carry) bit. If an error 
occurs, the system call sets the error bit; otherwise, the bit is 
cleared. The assemblers support the mnemonics "bes" (branch if error 
set) and "bee" (branch if error clear), which are synonymous with "bes" 
and "bcc". 
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Several system calls, such as "read" and "ttime" return data to a buffer 
whose address is specified when the call is invoked. In such a case the 
buffer must be in either the data segment or the stack. It may not be 
located in the text segment. 


Several files containing definitions used by the operating system reside 
in the directory "/lib". The user can include any of these definitions 
in a program by using the appropriate file as a library. A description 
of each of these files follows: 


sysdef 

syserrors 

sysf cntl 

sysints 

sysmessages 

syspty 

sysrump 

sysstat 

systime 

systty 

sys68881 


Defines the correspondence between the names and 
numbers of UniFLEX system calls. 

Defines the correspondence between the names and 
numbers of UniFLEX errors. Also contains a 
brief definition of the most general cause of 
each error. 

Defines the correspondence between the names and 
numbers of the subfunctions used by the "fcntl" 
system call. Also defines the constants used by 
this system call. 

Defines the correspondence between the names and 
numbers of UniFLEX interrupts. Also contains a 
brief definition of each interrupt. 

Defines the structure of the buffer returned by 
the "msg status" system call. 

Defines the correspondence between the names and 
the numbers of the subfunctions used by the 
"control_pty " system call. Also defines the 
constants used by this system call. 

Defines the correspondence between the names and 
the numbers of the subfunctions used by the 
"rump" system call. 

Defines the structure of the buffer returned by 
the "ofstat" and "status" system calls. Also 
defines the file-permission flags. 

Defines the structures of the buffers returned 
by the "time" and "ttime" system calls. 

Defines the structure of the buffer returned by 
the "ttyget" and "ttyset" system calls. Also 
defines the constants used by these system 
calls. 

Defines the structure of the buffer used by the 
"FPU_exception" system call. 
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Syntax Conventions 


The following conventions are used in syntax statements 
throughout this manual. 

1. Items that are not enclosed in angle brackets, 

and '>' > or square brackets, '[ ' and , are 
'’keywords 11 and should be typed as shown. 

2. Angle brackets, and '>', enclose descriptions 

which the user must replace with a specific 

argument. Expressions enclosed only in angle 

brackets are essential parts of the syntax. For 
example, in the system call 

sys ind,<cal l_address> 

the address of the system call to execute must 
replace the term <call_address> . 

3. Square brackets, '[ ' and indicate optional 

items. These items may be omitted if their effect 
is not desired. 

4. The underscore character, is used to link 

separate words that describe one term, such as 
"call" and "address". 

5. Characters other than spaces that are not enclosed 

in angle brackets or square brackets must appear in 

the command line as they appear in the syntax 

statement. 


TSC 3/17/86 




System Call Summaries 


alarm 

break 

cdata 

chacc 

chdir 

chown 

chprm 

close 

control_j>ty 

cpint 


create 

create_contiguous 
cr eate__pty 
crpipe 
crtsd 

deface 

dup 

dups 

exec 
exece 
f cntl 
f il tim 

fork 

FPU_except ion 


FPU__resume 

gpid 

gtid 

guid 
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Send an alarm interrupt to the current 
task after the specified interval. 

Change the size of the data segment 
associated with the task. 

Change the amount of physically contiguous 
memory associated with the task. 

Check the permissions on the specified 
file. 

Make the specified directory the user's 
working directory. 

Change the owner of a file. 

Change the access permissions of the 
specified f ile. 

Close an open file. 

Adjust or report the modes of operation of 
a pseudoterminal. 

Inform the operating system how to behave 
when the current task receives one kind of 
interrupt . 

Create a new file or truncate an existing 
file to a length of 0. 

Create a new contiguous file. 

Open an unused pseudot erminal channel. 
Create a pipe. 

Create a special file (a device) or a new 
directory. 

Set the default access permissions for all 
files created by this task. 

Duplicate the specified file descriptor. 
Duplicate a file descriptor onto the 
specified file descriptor. 

Execute a program. 

Execute a program. 

Change or query the behavior of a file. 
Change the time of last modification of 
the specified file. 

Create a new task. 

Return or update information about an 
exception generated by the MC68881 
floating-point coprocessor. 

Resume execution of the MC68881 
instruction that generated an exception. 

Get the task ID of the parent of the 
current task. 

Get the task ID of the current task. 

Return the user ID and the effective user 
ID of the person executing the current 
task. 
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System call summaries- 2 


ind 

indx 

link 

lock 

lrec 

make realtime 


memman 

mount 


msg attach 
msg__detach 
msg_receive 

msg_send 

msg_status 

of stat 

open 

phys 

profile 

read 

rump 

sacct 

seek 

setpr 

se t_high_addr es s_mask 

spint 

stack 

stack_limit 

status 

stime 

stop 

suid 

term 

time 

truncate 

ttime 

ttyget 


Execute the system call located at the specified 
address. 

Execute the system call located at the specified 
address. 

Create a link to a file. 

Lock a task in memory or unlock a locked task. 

Add an entry to the operating system's lock 
table. 

Make a non-real-time task a real-time task and 
set its relative priority, or make a real-time 
task a non-real-time task. 

Perform a memory-management operation. 

Insert the medium in the specified block device 
at the node of the directory tree specified by 
<dir__name>. 

Attach a task to a message exchange. 

Detach a task from a message exchange. 

Receive a message from another task via a message 
exchange. 

Send a message to another task via a message 
exchange. 

Obtain information about the status of a message 
exchange. 

Get the status of an open file. 

Open an existing file. 

Obtain or release access to a section of system 
memory. 

Start or stop monitoring the current task. 

Read data from an open file. 

Create, destroy, access, or relinquish access to 
a named resource. 

Enable or disable system accounting procedures. 
Change the current file position of an open file. 
Change the priority bias of the current task. 

Load the specified value into the register for 
the hardware address mask. 

Send an interrupt to a task. 

Extend the stack space of the current task. 

Specify a limit to the task's stack segment. 

Get the status of a file. 

Set the system date and time. 

Suspend the current task. 

Set both the user ID and the effective user ID. 
Terminate the current task. 

Get the system time and other related parameters. 
Set the size of an open file. 

Get the information on the use of the CPU by the 
current task and its child tasks. 

Get information on the configuration of a 
terminal. 
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System call summaries-3 


ttynum 

ttyset 
uni ink 
unmnt 
update 
urec 

vfork 

wait 

write 

yield_CPU 


Get the terminal number of the task's controlling 
terminal. 

Set the configuration of a terminal. 

Remove a link to a file. 

Unmount the medium in a device. 

Update all disks on the system. 

Remove an entry from the operating system's lock 
table. 

Create a new task. 

Suspend the task until a child task terminates. 
Write data to an open file. 

Yield the CPU to another task of equal priority. 
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Syntax Summaries 


Expected: 

Syntax: 

Returned: 

Syntax: 

Syntax: 

Syntax: 

Syntax: 

Syntax: 

Syntax: 

Expected: 

Syntax: 

Expected: 
Syntax: 
Returns : 

Syntax: 
Returns : 

Syntax: 
Returns : 

Syntax: 

Returns : 

Expected: 

Syntax: 

Syntax: 
Returns : 

Syntax: 

Syntax: 
Returns : 


<seconds> in DO 
sys alarm 

<previous_seconds > in DO 

sys break, <high__addr ess> 

sys cdata ,<high_address> 

sys chacc , <f il e__name> , <perm__mask> 

sys chdir , <dir__name> 

sys chown, <f il e__name> ,<owner_ID> 

sys chprm,<f ile_name>,<perm_mask> 

<file__des> in DO 
sys close 

<file_des> in DO 

sys control_j>ty , <f unct ion_code> ,<mode_f lag> 

<state_f lag> in DO 

sys cpint , <interrupt >, <address> 

<old__address> in DO 

sys create , <f il e__name> , <perm_mask> 

<file_des> in DO 

sys create__contiguous , <f ile__name> , <penn_mask> ,<f ile_size>, 

<zero_f lag> 

<file_des> in DO 

<slave_f ile__des> in DO 
<master_f ile__des> in AO 
sys create_pty 

sys crpipe 

<read_f ile_des> in DO 
<write_f ile_des> in AO 

sys crtsd , <f ile_name> , <de script or > ,<dev_num> 

sys deface, <perm_jnask> 

<previous_mask> in DO 
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Expected: 

Syntax: 

Re turns : 

Expected: 

Syntax: 

Returns: 

Syntax: 

Syntax: 

Expected: 
Syntax: 
Returns : 
or 


Expected: 

Syntax: 

Syntax: 
Returns : 


Syntax: 

Syntax: 

Syntax: 
Returns : 

Syntax: 
Returns : 

Syntax: 
Returns : 


Syntax: 

Expected: 

Syntax: 

Syntax: 

Syntax: 

Expected: 

Syntax: 


<file_des> in DO 
sys dup 

<new_f ile_des> in DO 

<file_des> in DO 
<requested_f ile_des> in AO 
sys dups 

<requested_f ile_des> in DO 

sys exec.<file name>.<arg list> 

sys exece , <f il e_name> , <arg^_l is t > , <env_l is t > 

<file_des_l> in DO 

sys f cntl, <function_code> 

<access_f lag> in DO 

<file_des_2> in DO 

<time> in DO 

sys f iltim,<f ile_name> 

sys fork 

To parent task: <child_task's_ID> in DO 
To child task: 0 in DO 

sys FPU_exception, <function_code>,<buf_add> 
sys FPU_resume 
sys gpid 

<parent_task_ID> in DO 

sys gtid 
<task_ID> in DO 

sys guid 

<user_ID> in DO 

<ef f ective_user_ID> in AO 

sys ind,<call_address> 

<call_address> in AO 
sys indx 

sys 1 ink, <f il e_name_l > , <f il e_name_2> 

lock,<function_code> 

<file_des> in DO 
sys lrec,<count> 
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Syntax summaries- 


Expected: <relative_priority> in DO 
Syntax: sys make_real time 

Syntax: sys memman, <f unction_code>, <start_ address>, <end_address> 

Syntax : sys mount , <dev_name> , <dir_name> , <mode> 

Syntax: sys msg_attach, <exchange_name>, <mode> 

Returns: <exchange__ID> in DO 

Expected: <exchange_ID> in DO 
Syntax: sys msg_detach 

Expected: <exchange__ID> in DO 

Syntax: sys msg_receive, <buf_add>,<mode> 

Expected: <exchange__ID> in DO 

Syntax: sys msg_send , <buf__add> , <mode> 

Expected: <exchange__ID> in DO 
Syntax: sys msg__status , <buf_add> 

Expected: <file___des> in DO 
Syntax: sys of stat , <buf_add> 

Syntax: sys open, <f ile_jiame>, <mode> 

Returns: <file__des> in DO 

Syntax: sys phys , [ -] <code> 

Returns: <log__base_add> in DO (only when obtaining access to memory) 

Syntax: sys prof ile, <start_add>,<buf_add>,<size>,<scale> 

Expected: <file_des> in DO 

Syntax: sys read, <buf_add>, <count > 

Returns : <by tes_read> 

Expected: <f unction_code> in DO 
<resource_jiame> in AO 
Syntax: sys rump 

Syntax: sys sacct , <f ile_name> 

Expected: <file_des> in DO 

Syntax: sys seek, <count>, <pt_pf_origin> 

Returns : <new_position> 

Expected: <priority_bias> in DO 
Syntax: sys setpr 
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Expected : 
Syntax: 

Expected: 

Syntax: 

Expected: 

Syntax: 

Expected: 
Syntax: 
Returns : 

Syntax: 

Expected: 

Syntax: 

Syntax: 

Expected: 

Syntax: 

Expected: 

Syntax: 

Syntax: 

Expected: 

Syntax: 

Syntax: 

Expected: 
Syntax : 

Syntax: 
Returns : 

Expected: 

Syntax: 

Syntax: 

Syntax: 

Syntax: 

Expected: 

Syntax: 


<address__mask> in DO 
sys set_high_addr ess_mask 

<task_ID> in DO 
sys spint , <interrupt > 

<address> in DO 
sys stack 

<address> in AO 
sys stack_limit 
<previous_limit> in DO 

sys status , <f il e_name>, <buf__add> 

<time> in DO 
sys stime 

sys stop 

<user__JLD> in DO 
sys suid 

<term__status> in DO 
sys term 

sys time,<buf_add> 

<file_des> in DO 
sys truncate 

sys ttime, <buf__add> 

<file_des> in DO 
sys ttyget , <buf_add> 

sys ttynum 
<tty_num> in DO 

<file_des> in DO 
sys tty set, <buf_add> 

sys unlink, <f ile_name> 

sys unmnt , <dev_name> 

sys update 

<file_des> in DO 
sys urec 
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Syntax: sys vfork 

Returns: To parent task: <child_task's_ID> in DO 

To child task: 0 in DO 


Syntax: sys wait 

Returns: <task_ID> in DO 

<term status> in AO 


Expected: <file_des> in DO 

Syntax: sys write, <buf_add>,<count> 

Returns: <bytes_written> 

Syntax: sys yield_CPU 
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alarm 

Send an alarm interrupt to the current task after the specified 
interval. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<seconds> in DO 
Syntax Statement 
sys alarm 
Returns 

<previous__seconds > in DO 
Arguments 

<seconds> The number of seconds to wait before 

sending the alarm interrupt. A value of 
0 cancels any existing request for an 
alarm interrupt and does not generate a 
new one. 

<previous__seconds> The number of seconds remaining from the 

previous request for an alarm interrupt 
or 0 if the user made no previous 
request . 

DESCRIPTION 

The "alarm 11 system call sets the task's alarm clock to send an alarm 
interrupt (SIGALARM) after the interval specified in the DO register has 
elapsed. If the alarm clock is already set, the call overrides the 
previous setting. Unless the program catches or ignores it, the 

interrupt terminates the task. The system call returns control to the 
caller immediately after execution. 


NOTES 

. The time that elapses before the system sends the alarm interrupt 
may be slightly less than the requested time because the system 
ticks occur at one-second intervals. 
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. The time that elapses before the system sends an alarm interrupt to 
a task that invoked the call with a value of 1 for <seconds> may be 
more than 1 second if the time until the next 1-second interval in 
the system is small. 


SEE ALSO 

cpint 

stop 
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break 

Change the size of the data segment associated with the task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys break, <high_address> 

Arguments 

<high_address> The highest address to be used by the task for 
data space. 


DESCRIPTION 

The "break" system call sets the end-of-segment address for the data 
segment of the task. If <high_address> is higher than the data 
segment's current end-of-segment address, "break” allocates memory to 
the segment; if it is lower, "break" relinquishes memory to the system. 


ERRORS REPORTED 
EDTOF 

Not enough memory is available to honor the request. 


SEE ALSO 
cdata 
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cdata 

Change the amount of physically contiguous memory associated with the 
task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys cdata , <high_address> 

Arguments 

<high__address> The highest address to be used by the task for 
data space. 

DESCRIPTION 

The "cdata" system call sets the end-of-segment address for the data 
segment of the task. The system allocates physically contiguous memory 
to the task and locks the contiguous pages in memory so that they will 
remain contiguous. If <high_address> is higher than the data segment's 
current end-of-segment address, "cdata" allocates memory to the segment; 
if it is lower than the data segment's current address but higher than 
the lowest address in the data segment, "cdata" relinquishes memory to 
the system; if it is lower than the lowest address in the data segment, 
"cdata" neither allocates nor releases memory. 


ERRORS REPORTED 
EDTOF 

Not enough memory is available to honor the request. 


SEE ALSO 
break 
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chacc 

Check the permissions on the specified file. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys chacc , <f il e__name> , <penn_mask> 

Arguments 

<file_jname> The address of the nul 1-terminated name of the 
file to check. 

<perm__mask> An 8-bit mask specifying which permissions to 
check for. If the value of <perm_mask> is 0, 
the system call checks for the existence of the 
specified file and for execute permission on all 
directories in the path leading to the file. 
The following table shows the correspondence 
between other values of <perm_mask> and the 
permissions to check. The file "/lib/sysstat " 
defines the constants whose names are shown in 
parentheses. Any combination of these values is 
valid. 


<perm_jnask> Permission to Check 


0001 Read (FACUR or FACOR) 

0010 Write (FACUW or FACOW) 

0100 Execute (FACUE or FACOE) 


DESCRIPTION 

The "chacc" system call checks to see whether or not the specified 
permissions are set for the user on <file_name>. 


ERRORS REPORTED 
EMSDR 

The path to <file_jiame> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 
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ENOFL 

No file on the system corresponds to the specified name. 

EPRM 

The permissions set on the specified file do not grant the requested 
type of access. 

SEE ALSO 
chprm 
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chdir 

Make the specified directory the user's working directory. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys chdir, <dir_name> 

Arguments 

<dir_name> The address of the null-terminated name of the 
directory to be the working directory. 


DESCRIPTION 

The "chdir" system call changes the working directory to that specified 
by <dir_name>. 


ERRORS REPORTED 
EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 
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chown 


Change the owner of a file. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys chown, <f ile_name> ,<owner_ID> 
Arguments 


<f ile_name> 

The address of the null-terminated 
file whose owner is to change. 

name 

of 

the 

<owner__ID> 

The user identification number (ID) 

of 

the 

new 


owner of the specified file. It need not be an 
ID found in the password file. The maximum 
permissible value is hexadecimal FFFF. 


DESCRIPTION 

The "chown 11 system call changes the owner of the specified file to the 
user specified by <owner__ID>. Only the system manager may invoke this 
system call. 


ERRORS REPORTED 
EMSDR 

The path to <file__name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 
ENOFL 

No file on the system corresponds to the specified name. 
EPRM 

The current effective user is not the system manager. 


SEE ALSO 

chprm 
of stat 
stat 
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chprm 

Change the access permissions of the specified file. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys chprm, <f ile__name> ,<perm_mask> 

Arguments 

<file__name> The address of the null-terminated name of the 
file whose permissions are to change. 

<perm_mask> An 8-bit mask specifying the new permissions for 
the file. The following table shows the 
permission that is assigned to the file as each 
bit is set. The file "/lib/sysstat ,f defines the 
constants whose names are shown in parentheses. 
Any combination of bits is valid. 


<perajmask> Permission Assigned 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 

01000000 


Owner read permission (FACUR) 

Owner write permission (FACUW) 

Owner execute permission (FACUE) 
Others read permission (FACOR) 
Others write permission (FACOW) 
Others execute permission (FACOE) 
Set user-ID bit for execute (FXSET) 


If the specified file is a directory, FACUE 
grants permissions to the user who owns the file 
to search the directory for the name of a file; 
FACOE grants the same permission to other users. 
When the user-ID bit is set, the operating 
system grants to any user who executes the file 
the same permissions as it grants to the owner 
of the file for the duration of the task. 


DESCRIPTION 

The ,f chprm ,f system call changes the set of access permissions associated 
with the specified file to those described in <perm__mask> . Only the 
system manager or the owner of the specified file may execute this 
system call. 
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ERRORS REPORTED 
EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 

ENOFL 

No file on the system corresponds to the specified name. 

EPRM 

The current effective user is neither the system manager nor the 
owner of the specified file. 


SEE ALSO 

chown 
of stat 
stat 
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close 

Close an open file. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 
sys close 
Arguments 

<file_des> The file descriptor of the file to close. 


DESCRIPTION 

The "close" system call closes the specified open file. The operating 
system automatically closes all files used by a task when the task 
terminates, but it is good practice to explicitly close a file as soon 
as the task is finished with it. As it closes a file, "close" checks 
its link count. If the link count is 0, "close" deletes the file from 
the system. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file. 
EBARG 

An argument to the system call is invalid. 


SEE ALSO 

create 

create__pty 

crpipe 

dup 

dups 

open 
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control_pty 

Adjust or report the modes of operation of a pseudoterminal. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 


sys control_pty , <f unct ion_code>, <mode_f lag> 


Returns 

<state__f lag> in DO 


Arguments 


<f ile_des> 

<f unct ion__code> 
<mode_f lag> 


<state__flag> 


The file descriptor of the master task of 
the pseudoterminal to control. 

The subfunction to perform. 

A flag used with PTY_J$ETJMQDE to describe 
the desired modes of behavior of the 
pseudoterminal. All other subfunctions 
ignore this flag, but because the system 
call expects this argument, a value of 0 
should be used in the syntax statement. 

A flag describing the current state of the 
specified pseudoterminal. 


DESCRIPTION 

The operating system creates a pseudoterminal in a particular state 
which includes both modes of behavior which the user can directly alter 
and conditions reflecting the current usage of the pseudoterminal, which 
the user cannot directly alter. The M control_j>ty ,f system call adjusts 
or reports the state of the specified pseudoterminal. 

The modes of behavior are defined in the low-order byte of <state__f lag> , 
which is always returned to DO by "control _j?ty ". When the operating 
system creates a pseudoterminal, none of these bits is set — that is, 
none of the modes of behavior is in effect. The structure of this byte, 
which is defined in the file M /lib/syspty ", is as follows: 
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! 7 ! 6 ! 5 ! 4 ! 3 ! 2 ! 1 ! 0 ! 


!!!!!!!! 

!!!!!!!- 

!!!!!! 

! ! ! ! ! — 

! ! ! j 

j j j 

j j 


By default, a "read" call from the master task returns only the data 
written by the slave task. If PTY_PACKET_MODE is in effect (bit 0 is 
set), a "read" system call returns two bytes of information in addition 
to any data read. If data are available, these additional bytes are 
both null. Otherwise, they contain information describing the state of 
the pseudoterminal — that is, <state_f lag>. 

By default, characters written from the master task to the 
pseudoterminal are processed normally, not as if the channel to the 
master task were in raw mode. If PTY_REMOTE_MODE is in effect, the 
pseudoterminal treats all input it receives from the master task as if 
the channel to the master task were in raw mode. 

By default, the operating system performs a "read" system call from the 
master task whether or not data are available and completes a "write" 
system call before a slave has consumed the data. If PTY_READ_WAIT mode 
is in effect, the system puts a "read" system call from the master task 
to sleep until data are available. Similarly, if PTY_HANDSHAKE_MODE is 
in effect, it puts a "write" system call from the master task to sleep 
until a slave has consumed the data. 

Finally, by default the system does nothing to prevent any slave task 
from writing to the pseudoterminal. If, however, PTY_SLAVE_HOLD mode is 
in effect, the system prohibits all slave tasks from writing to the 
pseudoterminal. 

The high-order byte of <state_flag> reflects conditions that the user 
cannot alter with the "control_pty" command. The structure of this 
byte, which is defined in the file "/lib/syspty", is as follows: 


PTY_PACKET_MODE 
PTY_REMOTE_MODE 
PT Y_READ_WAIT 
spare 

PTY_HANDSHAKE_MODE 

spare 

spare 

PTY SLAVE HOLD 
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!7!6!5!4!3!2!1!0! 


!!!!!! 

! ! ! ! ! PTY_EOF 

! ! ! ! PTY_OUTPUT_QUEUED 

! ! ! PTY_INPUT_QUEUED 

I j spare 

j spare 

spare 

spare 

spare 

When bit 0 (PTY_EOF) is set, all accesses to the pseudoterminal from 
slave tasks are closed. When bit 1 (PTY_OUTPUT_QUEUED) is set, a slave 
task has written data to the pseudoterminal , but the master task has not 
yet consumed it. When bit 2 (PTY_JLNPUT_QUEUED) is set, the master has 
written data to the pseudoterminal, but a slave task has not yet 
consumed it. 

The "control^pty 1 * system call supports six subfunctions, which are 
defined in the file "/ lib/syspty ,f as follows: 



Code Subfunction 


0 PTYJLNQUIRY 

1 PTY_SETJMODE 

2 not used 

3 PTY_FLUSH_READ 

4 PTYJFLUSHJWRITE 

5 PTY_ST0P_0UTPUT 

6 PTY_START_OUTPUT 

A description of each of these subfunctions follows: 


PTY_INQUIRY 
PTY SET MODE 


PTY_FLUSH_READ 
PTY FLUSH WRITE 


Report the current state of the 
pseudoterminal, but alter nothing. 

Rewrite the low-order byte of <state_flag> 
from the value of <mode__f lag> specified by 
the user. This subfunction allows the user 
to alter all modes of behavior 
simultaneously. 

Delete any data written by the master task 
that has not yet been consumed by a slave 
task. 

Delete any data written by a slave task 
that has not yet been consumed by the 
master task. 
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PTY_STOP_OUTPUT Prevent all slave tasks from writing any 

more data to the master task (enable 
PTY_SLAVE_HOLD mode). 

PTY_START_OUTPUT Allow all slave tasks to write data to the 

master task (disable PTY_SLAVE_HOLD mode) . 

NOTES 

. Pseudoterminals are a vendor-dependent option and may not be 
supported by all systems. 

ERRORS REPORTED 
EBARG 

An argument to the function is invalid. 

EIO 

The file descriptor specified corresponds to access in slave mode; 
it must correspond to access in master mode. 

SEE ALSO 

create_pty 
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cpint 

Inform the operating system how to behave when the current task receives 
one kind of interrupt. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys cpint ,< inter rupt >,<addr ess > 

Returns 

<old_address> in DO 
Arguments 

<interrupt> The kind of interrupt to be handled by this 
system call. 

<address> The interrupt-handling address for 

<interrupt> — that is, the address to which 
control should pass whenever the current task 
receives the specified kind of interrupt. A 
value of 0 tells the operating system to take 
the default action for the interrupt (usually 
termination of the task). A value of 1 or any 
other odd address tells the operating system to 
ignore the interrupt. 

<old__address> The previous interrupt-handling address for the 
specified kind of interrupt. 

DESCRIPTION 

The "cpint" system call tells the operating system how to behave when 
the current task receives the specified interrupt. When the 
interrupt-handling address is an even, nonzero address, the operating 
system passes control to that address when the current task receives the 
specified interrupt. After processing the interrupt as specified at the 
interrupt-handling address, the operating system resets itself so as to 
take the default action the next time the current task receives the same 
kind of interrupt. Therefore, in order to continue to catch the same 
kind of interrupt, the code at the interrupt-handling address should 
reinvoke "cpint" before returning control to the point at which the 
interrupt occurred. 

When the interrupt-handling address is 0 or any odd address, the 
operating system does not actually pass control to that address (see 
Arguments) and does not reset itself to take the default action the next 
time the same kind of interrupt occurs. 
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The file "/lib/sysints" defines the interrupts whose names are shown in 
the table accompanying this document. 

If not caught or ignored, the default behavior of each program interrupt 
(except SIGDEAD and SIGDUMP) is to terminate the task to which it is 

sent. As shown in the table, some also produce a "core dump". A core 

dump is a file called "core" in the working directory which contains the 

task's image of the contents of memory. Each byte in the program and 

stack space is written to the core file immediately after receipt of the 
interrupt. The user can examine this file to determine the state of 
memory at the time the interrupt was received. A core file is often 
useful for diagnostic purposes. The operating system will not create a 
core file if the working directory contains a file named "core" which 
denies write permission to the current effective user or if the working 
directory denies write permission to the current effective user. 

The default action for the SIGDUMP interrupt is to create a core dump 
and return control to the task. The task is not terminated. 

A vendor may use a TRAP instruction with a number greater than 6. In 
such a case the user should not issue the instruction. 

User-defined interrupts are available to the end user. 

For further information on program interrupts see Section 6.4 of the 
6 8 xxx UniFLEX Programmer 's Guide . 
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Table 1. Table of Interrupts 


Name 

Number 

Description 

A 

c 

D 

i 

R 

SIGHUP 

i 

Hangup 

4 

4 

- 

4 

4 

SIGINT 

2 

Keyboard 

+ 

4 

- 

4 

4 

SIGQUIT 

3 

Quit 

+ 

4 

4 

4 

4 

SIGEMT 

4 

A-line (Axxx) emulation trap 

+ 

4 

4 

4 

4 

SIGKILL 

5 

Task kill 

+ 

- 

- 

- 

4 

SIGPIPE 

6 

Broken pipe 

+ 

4 

- 

4 

4 

SIGSWAP 

7 

Swap error 

+ 

4 

- 

- 

4 

SIGTRACE 

8 

Trace 

+ 

4 

- 

4 

- 

SIGTIME 

9 

Time limit 

+ 

4 

4 

- 

4 

SIGALRM 

10 

Alarm 

+ 

4 

- 

4 

4 

SIGTERM 

11 

Task terminate 

4 

4 

- 

4 

4 

SIGTRAPV 

12 

TRAPV instruction 

4 

4 

4 

4 

4 

SIGCHK 

13 

CHK instruction 

4 

4 

4 

4 

4 

SIGEMT2 

14 

F-line (Fxxx) emulation trap 

+ 

4 

4 

4 

4 

SIGTRAPl 

15 

TRAP #1 instruction 

+ 

4 

4 

4 

4 

SIGTRAP2 

16 

TRAP #2 instruction 

4 

4 

4 

4 

4 

SIGTRAP3 

17 

TRAP #3 instruction 

4 - 

4 

4 

4 

4 

SIGTRAP4 

18 

TRAP #4 instruction 

4 

4 

4 

4 

4 

SIGTRAP5 

19 

TRAP #5 instruction 

+ 

4 

4 

4 

4 

SIGTRAP6 

20 

TRAP #6-14 instruction 

4 * 

4 

4 

4 

4 

SIGPAR 

21 

Parity error 

4 

4 

4 

- 

4 

SIGILL 

22 

Illegal instruction 

4 

4 

4 

- 

4 

SIGDIV 

23 

Division by 0 

4 

4 

4 

4 

4 

SIGPRIV 

24 

Privileged instruction 

4 

4 

4 

- 

4 

SIGADDR 

25 

Address error 

+ 

4 

4 

- 

4 

SIGDEAD 

26 

A child task terminated 

- 

4 

- 

4 

4 

SIGWRIT 

27 

Write to read-only memory 

4 

4 

4 

- 

4 

SIGEXEC 

28 

Data or stack space violation 

+ 

4 

4 

- 

4 

SIGBND 

29 

Segmentation violation 

4 

4 

4 

- 

4 

SIGUSR1 

30 

User-defined interrupt #1 

4 

4 

- 

4 

4 

SIGUSR2 

31 

User-defined interrupt #2 

4 

4 

- 

4 

4 

SIGUSR3 

32 

User-defined interrupt #3 

4 

4 

- 

4 

4 

SIGABORT 

33 

Program abort 

4 

- 

- 

- 

4 

SIGSPLR 

34 

Spooler signal 

4 

4 

- 

4 

4 

SIGINPUT 

35 

Input is ready 

4 

4 

- 

4 

4 

SIGDUMP 

36 

Take memory dump 

0 

4 

4 

4 

4 


37-41 

System-defined interrupts 






SIGUNORDERED 

42 

MC68881 branch or set on 
unordered operand 

4 

4 

“ 

4 

4 

SIGINEXACT 

43 

MC68881 inexact result 

4 

4 

- 

4 

4 

SIGFPDIVIDE 

44 

HC68881 division by 0 

4 

4 

- 

4 

4 

SIGUNDERFLOW 

45 

MC68881 underflow 

4 

4 

- 

4 

4 

SIG OPERAND 

46 

MC68881 invalid operand 

4 

4 

- 

4 

4 

SIGOVERFLOW 

47 

MC68881 overflow 

4 

4 

- 

4 

4 

SIGSNAN 

48 

MC68881 signaling not-a-number 

4 

4 

- 

4 

4 


49-63 

Vendor-defined interrupts 







Notes: A = Default state is "abort 11 (otherwise, "ignore") 

C = Interrupt can be caught 
D = Produces a core dump 
I = Interrupt can be ignored 
R = Resets to default state when triggered 
0 = See text 
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NOTES 

. The SIGTIME interrupt is not currently implemented. 


ERRORS REPORTED 
EBARG 

The value of <interrupt> is not a valid interrupt number 


SEE ALSO 
spint 

Commands : qdb 
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create 

Create a new file or truncate an existing file to a length of 0. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys create, <f ile_name> ,<perm_mask> 

Returns 

<file_des> in DO 
Arguments 

<file_name> The address of the null-terminated name to 
assign to the file, 

<perm__mask> An 8-bit mask specifying the permissions to 
assign to the file. The following table shows 
the permission that is assigned to the file as 
each bit is set. The file "/lib/sysstat" 
defines the constants whose names are shown in 
parentheses. Any combination of bits is valid. 

< perm_mask > Permission Assigned 


00000001 Owner read permission (FACUR) 

00000010 Owner write permission (FACUW) 

00000100 Owner execute permission (FACUE) 

00001000 Others read permission (FACOR) 

00010000 Others write permission (FACOW) 

00100000 Others execute permission (FACOE) 

01000000 Set user-ID bit for execute (FXSET) 

If the specified file is a directory, FACUE 
grants permissions to the user who owns the file 
to search the directory for the name of a file; 
FACOE grants the same permission to other users. 
When the user-ID bit is set, the operating 
system grants to any user who executes the file 
the same permissions as it grants to the owner 
of the file for the duration of the task. 
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DESCRIPTION 

The "create" system call creates a new file or truncates an existing 
file to a length of 0. If the file already exists, the system ignores 
<perm_mask> and, instead, leaves the original permissions intact. In 
such a case the owner of the file also remains the same. The effective 
user must have write permission in the specified existing file in order 
for the system call to succeed. 

If the file does not exist, the operating system creates a new file with 
the permissions specified by "anding" <perm_mask> with the l's 
complement of the mask defining the default permissions for creating a 
file with the current task. The owner of the file is the effective user 
when the task invokes the system call. The effective user must have 
write permission in the parent directory of the new file in order for 
the system call to succeed. 

In either case the "create" system call opens the specified file for 
writing whether or not the permissions grant such access to the 
effective user, and sets the current file position to the beginning of 
the file. 


NOTES 

. If the current task has the maximum permissible number of files open 
and the specified file does not exist, the "create" system call 
creates the file but does not open it. 


ERRORS REPORTED 
EDFUL 

The device which was to contain the file has no file descriptor 
nodes (fdns) available. 

EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 

EPRM 

The existing file or the parent of the new file does not grant the 
user write permission. 

ETMFL 

The current task already has open as many files as the operating 
system will allow. If the specified file does not already exist, 
the "create" system call creates it but cannot open it. 
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SEE ALSO 

chacc 

chprm 

create_contiguous 

deface 

open 
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cr ea te_cont iguous 
Create a new contiguous file. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys cr eat e_cont iguous , <f ile__name> , <perm_mask> , <f ile__size>, <zero_f lag> 
Returns 

<file_des> in DO 
Arguments 

<file_name> The address of the null-terminated name to 
assign to the file. 

<perm_mask> An 8-bit mask specifying the permissions to 
assign to the file. The following table shows 
the permission that is assigned to the file as 
each bit is set. The file M /lib/sysstat n 
defines the constants whose names are shown in 
parentheses. Any combination of bits is valid. 

<perm__mask> Permission Assigned 


00000001 Owner read permission (FACUR) 

00000010 Owner write permission (FACUW) 

00000100 Owner execute permission (FACUE) 

00001000 Others read permission (FACOR) 

00010000 Others write permission (FACOW) 

00100000 Others execute permission (FACOE) 

01000000 Set user-ID bit for execute (FXSET) 

When the user-ID bit is set, the operating 
system grants to any user who executes the file 
the same permissions as it grants to the owner 
of the file for the duration of the task. 
<file__size> The number of bytes to reserve for the file. 

This number must be a multiple of 512. 

<zero_flag> A flag which tells the operating system whether 
or not to fill the space allocated for the file 
with null bytes. Unless the specified value is 
0, the operating system does so. 
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DESCRIPTION 

The "create^contiguous" system call creates a new contiguous file. If 
the file already exists, the system ignores <perm_mask> and, instead, 
leaves the original permissions intact. In such a case the owner of the 
file also remains the same, and all information in the file at the time 
the system call is invoked is lost. The effective user must have write 
permission in the specified existing file in order for the system call 
to succeed. 

If the file does not exist and the disk has enough unused 
contiguous-file space, the operating system creates a new file with the 
permissions specified by "anding" <perm_jnask> with the l's complement of 
the mask defining the default permissions for creating a file with the 
current task. The owner of the file is the effective user when the task 
invokes the system call. The effective user must have write permission 
in the parent directory of the new file in order for the system call to 
succeed. 

In either case the "cr eate__contiguous M system call opens the specified 
file for writing whether or not the permissions grant such access to the 
effective user, and sets the current file position to the beginning of 
the file. 


NOTES 

. If the current task has the maximum permissible number of files open 
and the specified file does not exist, the ,f cr eate_contiguous M 
system call creates the file but does not open it. 

. Contiguous files are a vendor-dependent option and may not be 
supported by all systems. 


ERRORS REPORTED 
EBARG 

The value of <file_size> must be a multiple of 512. 

EBDCL 

The operating system does not support contiguous files. 

EDFUL 

The device which was to contain the file does not have enough 
contiguous-file space. 

EMSDR 

The path to <f ile__name> cannot be followed. 
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ENDR 

A part of the path to <file_name> is not a directory. 

EPRM 

The existing file or the parent directory of the new file does not 
grant the user write permission. 

ETMFL 

The current task already has open as many files as the operating 
system will allow. If the specified file does not already exist, 
the "create_contiguous" system call creates it but cannot open it. 


SEE ALSO 

create 

deface 
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create pty 

Open an unused pseudoterminal channel* 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<slave_f ile_des> in DO 
<master_f ile_des> in AO 

Syntax Statement 

sys create_pty 

Arguments 


<slave_JE ile__des> 

The file descriptor for 
pseudoterminal by a slave 

access 

task. 

to 

the 

<ma s t er_f i 1 e_de s > 

The file descriptor for 
pseudoterminal by a master 

access 

task. 

to 

the 


DESCRIPTION 

The "create_j>ty" system call opens an unused pseudoterminal channel. A 
pseudoterminal is a mechanism which allows one program to communicate 
with another task as if it were communicating with a terminal. The 
operating system treats a pseudoterminal like a device. The task which 
creates the pseudoterminal is the "master task"; the task or tasks with 
which the master task communicates are the "slave tasks". 

Before any task can open a channel to a pseudoterminal , the directory 
"/dev" must contain at least one pseudoterminal device. The system 
manager can create such a device with the "makdev" command as follows: 


makdev /dev/pty<num> p 1 <num> 

where <num> is a two-digit number between 00 and 99 inclusive. (The 
maximum number of pseudoterminals any system can support is 100; 
however, this maximum is system-dependent and may be less than 100 for 
any given system.) The numbers used to create all pseudoterminals on a 
system must be continuous and must start with 00. The "create__pty" 
system call returns access to the unused pseudoterminal with the lowest 
number . 

The operating system opens a pseudoterminal with the same configuration 
as a terminal. That is, the pseudoterminal is not in raw mode; it does 
not map upper- to lowercase; it is not in single character input mode. 
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It does echo input, echo the backspace character, expand tabs on output, 
output a line-feed character (hexadecimal OA) after each carriage 
return, and ignore control characters except for the carriage return, 
the horizontal tab character, control-C, control-D, control-\, the 
backspace character, and the line-cancel character. By default the 
backspace character is control-H; the line-cancel character, control-X. 
The master task or any slave task can alter these parameters with the 
"ttyset" system call. The configuration of the pseudoterminal reflects 
the most recent invocation of "ttyset". (For further details on the 
configuration of a terminal see the 68xxx UniFLEX Programmer s Guide ). 

The operating system creates a pseudoterminal with particular modes of 
operation in effect. This paragraph describes the default modes of 
operation. The operating system performs a "read" system call from the 
master task whether or not data are available. The "read" call from the 
master task returns only the data written by the slave task. Characters 
written from the master task to the pseudoterminal are processed 
normally, not as if the channel to the master task were in raw mode. 
The operating system completes a "write" system call from the master 
task before a slave task has consumed the data. Slave tasks may send 
data to the pseudoterminal. The state of all these modes can be altered 
with the "control_pty" system call. 

Once a channel to a pseudoterminal is open, additional slave tasks may 
access that pseudoterminal by invoking the "open" system call for the 
appropriate device. All tasks using a pseudoterminal can treat it 
exactly as they would treat a terminal. 

The "ofstat" system call may be used with a pseudoterminal. The call 
returns a status of FPMPTY for a master task and FPSPTY for a slave 
task. 


NOTES 

. Pseudoterminals are a vendor-dependent option and may not be 
supported by all systems. 


ERRORS REPORTED 
EBADF 

The device specified is not a pseudoterminal. 

EDFUL 

All available pseudoterminal channels are already open. If the 
number of pseudoterminals in the device directory is less than the 
maximum the system can support, the system manager can create more 
of them. 
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SEE ALSO 

control_pty 
of stat 
ttyget 

68xxx UniFLEX Programmer 's Guide 
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Create a pipe. 


crpipe 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys crpipe 
Returns 

<read_f ile_des> in DO 
<write__f ile_des> in AO 

Arguments 

<read__f ile_des> The file descriptor for reading from 

the pipe. 

<write_f ile_des> The file descriptor for writing to the 

pipe. 


DESCRIPTION 

A UniFLEX pipe is a special kind of file which passes the output from 
one task to another task as input. The "crpipe" system call creates a 
pipe. Typically, a task invokes this system call before a "fork" system 
call so that the child task and its parent task can communicate. The 
"fork" system call duplicates both of the pipe's file descriptors for 
the child task. After the fork is complete, the task that is going to 
write to the pipe should close <read__f ile__des>, and the task that - is 
going to read from it should close <write_f ile__des>. 

The operating system sets the end-of-file condition for a pipe when the 
pipe is empty and no file descriptors for writing are open. It returns 
a "broken pipe" condition if the writing task tries to write to the pipe 
when no file descriptors for reading are open. 

The operating system allows the task that is writing to the pipe to 
write up to 4,096 bytes before suspending that task. After the task 
that is reading from the pipe has read all of the data, the operating 
system wakes the first task and allows it to continue writing to the 
pipe. The operating system allows the task that is reading from the 
pipe to read whenever any data are in the pipe. If the task tries to 
read when the pipe is empty and a file descriptor for writing is open, 
the operating system puts the reading task to sleep until either the 
writing task sends data to the pipe or the end-of-file condition is set. 
If the writing task sends data to the pipe, the operating system wakes 
the reading task and allows it to read the data. If end-of-file is set, 


TSC 9/2/86 


(continued) 



crpipe-2 


the operating system wakes the task, and the "read” system call returns 
having read 0 bytes. 


NOTES 

. Because of the way in which the operating system determines the 
end-of-file and broken-pipe conditions, it is crucial for each task 
using the pipe to close the file descriptor it is not using. 
Failure to close the unused file descriptor for writing prevents the 
operating system from ever setting the end-of-file condition; 
failure to close the unused file descriptor for reading prevents the 
operating system from recognizing a broken pipe. 

. Either task associated with the pipe may use the "ofstat" system 
call to determine whether or not the pipe contains any data. If the 
file size of the pipe is 0, no data are in the pipe. Otherwise, the 
pipe contains data. 

. Either task associated with the pipe may use the "ofstat" system 
call to determine whether or not the other end of the pipe is 
closed. The value of the variable M st_cnt" returned by "ofstat" is 
the number of file descriptors open for the pipe. If this number is 
less than 2, one end of the pipe is closed. 


ERRORS REPORTED 


ETMFL 

The current task has open more than two less than the maximum number 
of open files the operating system permits a single task. Opening 
the two file descriptors required for a pipe would exceed this 
maximum. 


SEE ALSO 

close 

fork 

ofstat 

open 

read 

write 
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cr t sd 

Create a special file (a device) or a new directory. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys crtsd, <f il e_name> , <descr iptor >, <dev_num> 

Arguments 

<file__name> The address of the null- terminated name of the 
new device or directory. 

<descriptor> A 16-bit flag specifying the type of the new 
file and the access permissions to set for it. 
The low-order byte specifies the permissions. 
The following table shows the permission that 
is assigned to the file as each bit is set. 
The file "/lib/sy sstat" defines the constants 
whose names are shown in parentheses. Any 
combination of bits is valid. 


<perm_mask> Permission Assigned 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 

01000000 


Owner read permission (FACUR) 

Owner write permission (FACUW) 

Owner execute permission (FACUE) 
Others read permission (FACOR) 
Others write permission (FACOW) 
Others execute permission (FACOE) 
Set user-ID bit for execute (FXSET) 


If the specified file is a directory, FACUE 
grants permissions to the user who owns the 
file to search the directory for the name of a 
file; FACOE grants the same permission to other 
users. When the user-ID bit is set, the 
operating system grants to any user who 

executes the file the same permissions as it 
grants to the owner of the file for the 
duration of the task. 

The high-order byte specifies the type of file 
to create. The following table shows the valid 
bit patterns and the type of file each one 
creates : 
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<dev num> 


Bit Pattern Type of File 


00000010 

00000100 

00000110 

00001000 


Block device 
Character device 
Pseudoterminal 
Directory 


A 16-bit flag containing the major and minor 
device number for a block device, a character 
device, or a pseudoterminal. The high-order 
byte contains the major device number; the 
low-order byte, the minor device number. The 
major device number tells the operating system 
which set of device drivers to use for the 
device; the minor device number indicates which 
particular physical device to associate with 
the specified file. If the device being 

created is a directory, the "crtsd" call 
ignores this argument. 


DESCRIPTION 

The "crtsd” creates a block device, a character device, a pseudoterminal 
device, or a new directory. A block device transfers and receives data 
one block (512 K) at a time; a character device, one character at a 
time. A pseudoterminal is a mechanism which allows one program to 
communicate with another task as if it were communicating with a 
terminal. A directory is a file that contains a series of entries, each 
one consisting of the name of a file and a pointer to the file 
descriptor node (fdn) for that file. 

Only the system manager may invoke this system call. 


ERRORS REPORTED 
EBARG 

Either descriptor > or <dev__num> is invalid. 

EDFUL 

The device on which the user tried to create the special file is 
full. 

EFLX 

A file by the specified name already exists. 

EMSDR 

The path to <f ile_name> cannot be followed. 
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ENDR 

A part of the path to <file_name> is not a directory 
EPRM 

The current effective user is not the system manager 

SEE ALSO 

create 

create_pty 
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deface 

Set the default access permissions for all files created by this task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys deface, <perm_jnask> 

Returns 

<previous_mask> in DO 
Arguments 

<perm_mask> An 8-bit mask specifying the default 

permissions for all files created by the 
task invoking the "deface 11 system call. The 
following table shows the permission that is 
assigned to the file as each bit is set. 
Only the low-order 6 bits are set by 
"deface". The file "/lib/sysstat" defines 
the constants whose names are shown in 
parentheses. Any combination of bits is 
val id. 


<perm__mask> Permission Assigned 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 


Owner read permission (FACUR) 
Owner write permission (FACUW) 
Owner execute permission (FACUE) 
Others read permission (FACOR) 
Others write permission (FACOW) 
Others execute permission (FACOE) 


If the specified file is a directory, FACUE 
grants permissions to the user who owns the 
file to search the directory for the name of 
a file; FACOE grants the same permission to 
other users. 

<previous_jnask> The mask for default permissions that was in 
use prior to this invocation of the "deface" 
system call. 
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DESCRIPTION 

The '’deface 11 system call sets the default access permissions for all 
files created by the task invoking the call. When the operating system 
executes the "create" system call, it "ands" the value of the l's 
complement of the default permissions mask with the permissions mask 
specified by the user with the "create" system call. Thus, the 
operating system always disables permissions disabled by the default 
permissions mask regardless of the permission mask specified with 
"create". 

A "fork" or "exec" system call passes its <perm_mask> to every task it 
spawns. 


SEE ALSO 

create 

exec 

fork 

of stat 

stat 

vfork 
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dup 

Duplicate the specified file descriptor. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 
sys dup 
Returns 

<new_f ile_des> in DO 
Arguments 

<file__des> The file descriptor to duplicate. 

<new_f ile__des> The new file descriptor. 


DESCRIPTION 

The "dup" system call duplicates the specified file descriptor. To the 
user it appears that the operating system has again opened the file 
referenced by <file__des> in the same mode and with the same current 
position in the file. 


ERRORS REPORTED 
EBADF 

The file descriptor <file_des> does not reference an open file. 

EBARG 

An argument to the system call is invalid. 

ETMFL 

The operating system already has open as many files as it can. The 
system manager can alter the number of open files allowed with the 
"tune" command up to the system-dependent maximum. 


SEE ALSO 

dups 

open 

Commands : tune 


TSC 3/17/86 




dups-1 


dups 

Duplicate a file descriptor onto the specified file descriptor. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
<requested_f ile_des> in AO 

Syntax Statement 

sys dups 

Returns 

<requested_f ile_des> in DO 
Arguments 

<file_des> The file descriptor to duplicate. 

<requested_f ile_des> The file descriptor to use as the 

duplicate. 

DESCRIPTION 

The "dups" system call duplicates the specified file descriptor onto a 
specific file descriptor requested by the user. If the requested file 
descriptor references an open file, "dups" closes that file before 
proceeding. To the user it appears that the operating system has again 
opened the file referenced by <file_des> in the same mode and with the 
same current position in the file. 

ERRORS REPORTED 
EBADF 

The file descriptor <file_des> does not reference an open file. 

EBARG 

One or both of the file descriptors specified are out of range. 

SEE ALSO 
dup 
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exec 

Execute a program* 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys exec » <f il e name> ,<arg 1 is t > 

Arguments 

<file_name> The address of the null- terminated name of the 

file containing the program to execute* 

<arg list> The address of the list of addresses of the 

arguments to pass to the new program* Each 
argument must be a null-terminated character 
string. The list of arguments must be 
terminated by a null long-word. 

DESCRIPTION 

The "exec" system call tells the operating system to replace the program 
that is currently executing with the program found in the specified 
file. The operating system passes to the new program the arguments 
referenced by <arg__list> and begins executing the new program at its 
transfer address. 

The operating system sets up the new program's stack so that it contains 
the number of arguments to the new program, the address of each 
argument, and the arguments themselves. Following is a picture of the 
stack as execution begins: 
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... highest address in task space ... 

00 


argn : <argn> 


(The last null-terminated argument string) 


argO: <argO> 

00000000 

00000000 

argn 


argO 

sp -> <argcnt> 

. . . low memory . . . 


(The first nul 1-terminated argument string) 


(A pointer to the last nul 1-terminated 
argument string) 


(A pointer to the first argument string) 
(The number of arguments passed to the new 
task — a 4-byte quantity) 


At least two null bytes are left at the top of the task's address space. 


When the new program begins, it inherits the following attributes and 
resources from the calling program: 


The task's priority 

The task ID 

The parent task's ID 

The controlling terminal number 

The mask specifying the default permissions for creating a file 
The time remaining on an armed alarm clock 
The working directory 
All open files 

System and user time information 

If the user-ID bit is set on the file containing the calling program, 
the new program has as its effective user ID the ID of the owner of the 
file containing the new program. Otherwise, it inherits the user ID of 
the calling program. 

The new task ignores any interrupts that the calling program ignored. 
All other interrupts sent to the new task result in their default 
action, which is usually termination of the task. The operating system 
disables profiling in the new program. 
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The "exec" system call returns to the calling program only if it fails. 


ERRORS REPORTED 
EARGC 

The user specified too many arguments. The system allots 
approximately 4K for passing arguments. 

EBBIG 

The executable file is too large. The limit on the size of a file 
is machine-dependent. 

El SDR 

The specified file is a directory. 

EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 

ENOFL 

No file on the system corresponds to the specified name. 

ENOTB 

The file containing the new program is not an executable file or 
cannot be executed on the hardware. For example, a program which 
contains 68020-specific instructions cannot be executed by a 
68010-based machine. 

EPRM 

The permissions set on the specified file do not grant the requested 
type of access. 


SEE ALSO 

cpint 

exece 

fork 

profile 

vfork 
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exece 


Execute a program. 


ASSEMBLY LANGUAGE SYNTAX 


Syntax Statement 

sys exece, <f ile_name> ,<arg_list> , <env_list> 
Arguments 


<f ile__name> 
<arg list> 


<env list> 


The address of the null-terminated name of the 
file containing the program to execute. 

The address of the list of addresses of the 
arguments to pass to the new program. Each 
argument must be a nul 1- terminated character 
string. The list of arguments must be 
terminated by a null long-word. 

The address of the list of addresses of the 
environment parameters to pass to the new 
program. Each environment parameter must be a 
null-terminated character string. The list of 
environment parameters must be terminated by a 
null long -word. 


DESCRIPTION 

The "exece" system call tells the operating system to replace the 
program that is currently executing with the program found in the 
specified file. The operating system passes to the new program the 
arguments referenced by <arg__list> and the environment parameters 
referenced by <env_list>. It then begins executing the new program at 
its transfer address. 

The operating system sets up the new program's stack so that it contains 
the number of arguments to the new program, the address of each 
argument, the arguments themselves, the address of each environment 
parameter, and the parameters themselves. Following is a picture of the 
stack as execution begins: 
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. .. highest address in task space ... 

00 


envn: <envn> (The last null-terminated environment string) 


envO: <env> (The first null-terminated environment string) 

00000000 

argn: <argn> (The last null-terminated argument string) 


argO: <argO> (The first null-terminated argument string) 

00000000 

envn (A pointer to the last null-terminated 

. environment string) 

• 

• 

envO (A pointer to the first null-terminated 

environment string) 

00000000 

argn (A pointer to the last null-terminated 

. argument string) 

• 

argO (A pointer to the first null-terminated 

argument string) 

sp -> <argcnt> (The number of arguments passed to the new 

task — a 4-byte quantity) 

• . . low memory 

At least two null bytes are left at the top of the task's address space. 

When the new program begins, it inherits the following attributes and 
resources from the calling program: 

The task's priority 

The task ID 

The parent task's ID 

The controlling terminal number 

The mask specifying the default permissions for creating a file 
The time remaining on an armed alarm clock 
The working directory 
All open files 

System and user time information 
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If the user-ID bit is set on the file containing the calling program, 
the new program has as its effective user ID the ID of the owner of the 
file containing the new program. Otherwise, it inherits the user ID of 
the calling program. 

The new task ignores any interrupts that the calling program ignored. 
All other interrupts sent to the new task result in their default 
action, which is usually termination of the task. The operating system 
disables profiling in the new program. 

The "exece" system call returns to the calling program only if it fails. 


ERRORS REPORTED 
EARGC 

The user specified too many arguments. The system allots 
approximately 4K for passing arguments. 

EBBIG 

The executable file is too large. The limit on the size of a file 
is machine-dependent. 

EISDR 

The specified file is a directory. 

EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 

ENOFL 

No file on the system corresponds to the specified name. 

ENOTB 

The file containing the new program is not an executable file or 
cannot be executed on the hardware. For example, a program which 
contains 68020-specific instructions cannot be executed by a 

68010-based machine. 

EPRM 

The permissions set on the specified file do not grant the requested 
type of access. 

SEE ALSO 

cpint 

exec 

fork 

profile 

vfork 
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fcntl 

Change or query the behavior of a file. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<f ile_des_l> in DO 
Syntax Statement 

sys fcntl, <function_code> 
Returns 


<access_f lag> in DO 
or 

<file des 2> in DO 


Arguments 


<f ile__des__l> 

<function_code> 

<access__flag> 

<file des 2> 


The file descriptor of the file whose 
behavior to change or query. 

The subfunction to perform. 

A one-byte flag describing the mode of access 
to the file. 

The file descriptor of the last file which 
sent the signal INPUT READY to the current 
task. 


DESCRIPTION 

The "fcntl" system call queries or changes the way in which a task may 
access the specified file. The method of access is defined in 
<access__flag>, which may be returned to DO by "fcntl". When the 
operating system creates a file, none of these bits is set. Currently, 
the system uses only one bit of this flag, bit 0. By default, when a 
"read" system call tries to access a file, the operating system puts the 
task that issued the "read" call to sleep until data are available. 
When this bit is set, however, the operating system completes the system 
call whether or not data are available. 

The "fcntl" system call supports four subfunctions, which are defined in 
the file "/lib/sysf cntl". The following table shows the function code 
associated with each of these subfunctions: 
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Code Subfunction 


FCNTL_GET_PARAMS 
not used 
FCNTL_INPUT_FD 
FCNTL_NOB LOCK 
FCNTL_BLOCK 

A description of each of these subfunctions follows: 


0 

1 

2 

3 

4 


FCNTL_GET_PARAMS 
FCNTL INPUT FD 


FCNTL NO BLOCK 


FCNTL BLOCK 


Return <access_f lag> without altering any 
parameters. 

Return the file descriptor of the last file 
which sent the signal INPUT READY. When 

the user specifies this subfunction, the 
"fcntl" system call ignores <f ile_des_l>. 
Complete any "read" system call that 
attempts to access the file whether or not 
data are available. Return the error 
ENOINPUT if no data are available, and send 
the signal INPUT READY to the task when 
data become available. 

If no data are available, put to sleep 
until data become available any task 

issuing a "read" system call that attempts 
to access the specified file. 


NOTES 

. The INPUT READY signal is not sent to a task until a request to read 
from a file in NOBLOCK mode has been unsuccessful due to 
insufficient data. 


ERRORS REPORTED 
EBADF 

The value of <file_des_l> does not reference an open file. 
EBARG 

The subfunction code is invalid. 
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f il tim 

Change the time of last modification of the specified file. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<time> in DO 
Syntax Statement 

sys f il tim,<f ile_name> 

Arguments 

<time> The number of seconds that elapsed between 

midnight (00:00), January 1, 1980, and the 

desired last time of modification. 

<file_time> The address of the null-terminated name of the 
file to alter. 


DESCRIPTION 

The ,, filtim n system call changes the time of last modification of the 
specified file. It does not compare the new time of modification to 
either the time the file was created or the current time, so it is 
possible to set the file's modification time to a time before its 
creation or to a time in the future. 

Only the system manager may invoke this system call. 


ERRORS REPORTED 
EBARG 

An argument to the system call is invalid. 

EBSY 

The specified file is currently open. 

ENDR 

A part of the path to <f ile__name> is not a directory. 
ENOFL 

No file on the system corresponds to the specified name. 
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EPRM 

Either the file is on a device that is mounted for reading only or 
the current effective user is not the system manager. 


SEE ALSO 

of stat 
stat 
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fork 


Create a new task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys fork 
Returns 

To parent task: <child_task's__ID> in DO 
To child task: 0 in DO 

Arguments 

<child_task's_ID> The task ID assigned to the child task. 


DESCRIPTION 

The "fork" system call creates a new task (the child task) that is a 
copy of the current task (the parent task). The child task has the same 
priority, user ID, effective user-ID, controlling terminal information, 
default permissions-mask, working directory, signal handling set-up, and 
profiling information as the parent task. However, it differs from the 
parent task in the following ways: its task ID is different; its parent 
task-ID is the task ID of the parent task; its data are the same, but 
they are located in a different place in memory; its file descriptors 
are the same, but they are located in a different place in memory; its 
system and user CPU times are set to 0; its alarm clock is turned off. 

After a "fork" system call the child task resumes executions at the 
instruction immediately following the "fork" call. The parent task, on 
the other hand, resumes execution 2 bytes after the "fork" call. 
Obviously, then, the first instruction in the new task must be a short 
branch (requiring only 2 bytes). Each task determines where to resume 
by looking at the contents of the DO register immediately after 
execution of the "fork" call. 


ERRORS REPORTED 
ETMTS 

Either the maximum number of tasks allowed to a user or the maximum 
number of tasks allowed to the operating system has been reached. 
The system manager can alter either or both of these limits with the 
"tune" command up to the system-dependent maxima. 
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EVFORK 

The current task shares its memory with its parent and may 
invoke this system call. 

SEE ALSO 
vfork 


not 
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Return or update information about an exception generated by the MC68881 
floating-point coprocessor. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys FPU_except ion, <f unct ion_code>, <buf_add> 
Arguments 

<function code> 


<buf add> 


DESCRIPTION 

In order for the "FPU_except ion" system call to function, the user must 
have enabled exception processing by setting the appropriate bits in the 
MC68881 control register. A usable subset of exception processing can 
be enabled by setting a bit in the header of the binary file after 
assembly with the "headset" command. This subset is system-dependent, 
but in general it includes processing for exceptions generated by 
division by 0, overflow, and operand errors. A user who wishes to 
define exception processing directly from the assembly language program 
may do so with the "fmove" or "fmovem" instruction. 

If exception processing is enabled, the "FPU_exception" system call 
either copies the exception information from its location in memory into 
the specified buffer or copies the exception information in the buffer 
back to its location in memory. 

The file "/lib/sys68881 " defines the structure of the buffer as follows: 


The subfunction to perform. A value of 0 
tells the operating system to copy the 
exception information from its location in 
memory into the specified buffer; a value of 
1, to copy the exception information in the 
buffer back to its location in memory. 

The address of the buffer for the exception 
information. 
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* Buffer structure 
struct 0 


FPUstate 

ds. 1 

46 

State frame 

FPCR 

ds. 1 

1 

Control register 

FPSR 

ds. 1 

1 

Status register 

FPIAR 

ds. 1 

1 

Interrupt address register 

FPr egs 

ds.x 

8 

Data registers 


CPU_registers ds. 1 
CPU_D_registers ds.l 
CPU_A_r egisters ds.l 

CPU stack frame ds.w 


CPU_SR ds.w 
CPU_PC ds.l 
CPU_SFT ds . w 
CPU_PCX ds.l 
CPU_IR ds.w 
CPU_OP ds.w 
CPU EA ds.l 


0 

8 Data registers 
8 Address registers 

0 

1 Status register 
1 Program counter 
1 Stack frame type 
Program counter 
1 Internal register 
1 Operation word 
Effective address 


FPU INTERRUPT DATA SIZE ds.w 0 


* Definitions for control registers 


* Symbols ending in 

"^b" are bit numbers. 

* Symbols ending in 

"_bf" 

are bit-field specifications. 

FPCR_BSUN_b 

equ 

15 

Branch or set on unordered operand 

FPCR_SNAN_b 

equ 

14 

Signaling Not-a-Number 

FPCR_OPERR_b 

equ 

13 

Invalid operand 

FPCR_OVFL_b 

equ 

12 

Overflow 

FPCR_UNFL_b 

equ 

11 

Underflow 

FPCR_DZ_b 

equ 

10 

Division by 0 

FPCR_INEX2_b 

equ 

9 

Inexact result generated by an operation 

FPCR INEXl_b 

equ 

8 

Inexact result generated by decimal input 

FPCR_PREC_bf 

bf equ 

24:2 

Rounding precision (see below) 

FPCR_RND_bf 

bf equ 

26:2 

Rounding mode (see below) 


* Rounding precisions (FPCR_PREC_bf ) 


PREC_ 

.EXTENDED 

equ 

0 

Extended precision 

PREC" 

“single 

equ 

1 

Single 

precision 

PREC~ 

^DOUBLE 

equ 

2 

Double 

precision 
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* Rounding modes (FPCR_RND__bf ) 


RND_TO_NEAREST 

equ 

0 

Round 

toward nearest 


RND_TO_ZERO 

equ 

1 

Round 

toward zero 


RND_TO_MINU S 

equ 

2 

Round 

toward minus infinity 


RND_TO_PLUS 

equ 

3 

Round 

toward plus infinity 


* Definitions for status 

registers 


* Symbols ending 

in 

"_b" 

are i 

bit numbers. 


* Symbols ending 

in 

"_bf 

" are 

bit-f ield specifications. 


FPSR_N_b 


equ 

27 

Negative 


FPSR_Z_b 


equ 

26 

Zero 


FPSR_I_b 


equ 

25 

Inf inity 


FPSR_NAN_b 


equ 

24 

Not-a-Number or unordered 


FPSR_S_b 


equ 

23 

Sign of quotient 


FPSR_QUOTIENT_bf 

bf equ 

9:7 

Seven least-significant bits of quotient 

FP S R_B SU N_b 


equ 

15 

Branch or set on unordered 

operand 

FPSR_SNAN_b 


equ 

14 

Signaling Not-a-Number 


FP S R_OPERR_b 


equ 

13 

Invalid operand 


FPSR_OVFL_b 


equ 

12 

Overflow 


FPSR_UNFL_b 


equ 

11 

Underflow 


FPSR_DZ_b 


equ 

10 

Division by 0 


FPSR_INEX2_b 


equ 

9 

Inexact result generated by 

an operation 

FP S R_IN EX l_b 


equ 

8 

Inexact result generated by 

decimal input 

FPSR_IOP_b 


equ 

7 

Invalid operation 


FPSR_AOVFL_b 


equ 

6 

Accrued overflow 


FPSR_AUNFL_b 


equ 

5 

Accrued underflow 


FPSR_ADZ_b 


equ 

4 

Accrued division by 0 


FPSR_INEX_b 


equ 

3 

Accrued inexact 



NOTES 

. The user should use the "FPU^resume" system call to resume execution 
of the interrupted MC68881 instruction and to exit from the 
exception-handling routine. Using the "rtr" instruction may lead to 
unpredictable results because the program counter stored on the 
stack may be incorrect. 


ERRORS REPORTED 
ENOFPUDATA 

No exception information is available. 
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SEE ALSO 

FPU_resume 
Commands: headset 

68xxx UniFLEX Relocating Assembler and Linking-Loader 
Motorola, 1985. MC68881 Floating-Point Coprocessor User ^s Manual . 

Austin: Motorola. 
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FPU_resume 

Resume execution of the MC68881 instruction that generated an exception, 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys FPUjresume 

DESCRIPTION 

The "FPUjresume" system call resumes execution of an MC68881 instruction 
that generated an exception. It should be used at the end of an 
exception-handling routine instead of the "rtr" instruction. Use of the 
"rtr" instruction to exit from an exception-handling routine may lead to 
unpredictable results because the program counter stored on the stack 
may be incorrect. 

ERRORS REPORTED 
ENOFPUDATA 

No exception information is available. 

SEE ALSO 

FPU_exception 


TSC 3/17/86 




gpid-1 


gpid 

Get the task ID of the parent of the current task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys gpid 
Returns 

<parent_task_ID> in DO 
Arguments 

<parent_task_ID> The task ID of the parent of the current 

task. 

DESCRIPTION 

The "gpid" system call gets the task ID of the parent of the current 
task and returns it to the DO register. 


SEE ALSO 
gtid 
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gtid 

Get the task ID of the current task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys gtid 
Returns 

<task_ID> in DO 
Arguments 

<task_ID> The task ID of the current task. 

DESCRIPTION 

The "gtid" system call gets the task ID of the current task and 
it to the DO register. 


SEE ALSO 

exec 

fork 

gpid 

vfork 


returns 
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guid 

Return the user ID and the effective user ID of the person executing the 
current task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys guid 
Returns 

<user_ID> in DO 

<ef f ective_user_ID> in AO 

Arguments 

<user_ID> The user ID of the person who is logged 

in on the terminal from which the 
current task is being run. 

<ef f ect ive_user_ID> The user ID that defines the access 

permissions of the current task. If the 
task's user-ID bit is set, the effective 
user ID and the user ID may not be the 
same. 


DESCRIPTION 

The ,f guid ,f system call returns the user ID and the effective user ID of 
the person executing the current task. 

SEE ALSO 
suid 
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ind 

Execute the system call located at the specified address. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys ind,<call_address> 

Arguments 

<call_address> The address at which the system call to 
execute is located. 


DESCRIPTION 

The "ind" system call passes control to the specified address, which 
contains the system call to execute. This call is useful when the 
values of the arguments to the desired system call are not known prior 
to execution of the program. The user allocates space for the arguments 
in the assembly language program, and during execution the program moves 
the appropriate values to the proper location. 

The code located at <cal l_address> may invoke neither an "ind" nor an 
"indx" system call. 


ERRORS REPORTED 
EBDCL 

Either the code located at <call_address> does not invoke a valid 
UniFLEX system call, or it invokes an "ind" or "indx" system call. 


SEE ALSO 
indx 
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indx 

Execute the system call located at the specified address. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<call__address> in AO 
Syntax Statement 
sys indx 
Arguments 

<call__address> The address at which the system call to 
execute is located. 


DESCRIPTION 

The "indx" system call passes control to the address in the AO register, 
which contains the system call to execute. It is similar to the "ind" 
system call, but it allows the system call and its arguments to be 
located anywhere in memory, including the stack. This call is useful 
when the values of the arguments to the desired system call are not 
known prior to execution of the program. During execution the program 
moves the appropriate values to the proper location. 

The code located at <call__address> may invoke neither an "indx" nor an 
"ind" system call. 


ERRORS REPORTED 
EBDCL 

Either the code located at <call_address> does not invoke a valid 
UniFLEX system call, or it invokes an "ind" or "indx" system call. 

SEE ALSO 
ind 
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link 


Create a link to a file. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sy s 1 ink, <f il e_name_l > , <f il e_jiame_2> 

Arguments 

<f ile_name_l> The address of the null-terminated name of an 
existing file. The file may not be a 
directory unless the current effective user is 
the system manager. 

<f ile__name_2> The address of the null- terminated name of the 
file to link to <f ile_name_l>. This file must 
be nonexistent at the time the user invokes 
the system call. 


DESCRIPTION 

The "link" system call establishes a link between the specified existing 
file, <f ile_name___l>, and <f ile_jiame_2>. After the link is created, any 
reference to <f ile_name_2> references <f ile_jiame_J.>. Creation of the 
link does not alter the original file in any way except that the time of 
last modification is updated to the time the link was created. 

The operating system cannot link a file on one device to a file on 
another device. 

The directory containing the new link must grant write permission to the 
current effective user. The user must also have execute permission in 
all but the last component of both specified file names. 


NOTES 

. The maximum link count is 127. More than 127 links may exist, but 
the count itself neither increases nor decreases once it reaches 
127. Therefore, once a link count reaches 127, neither the "kill" 
command nor the "unlink" system call can remove the file from the 
system because the link count cannot reach 0. The removal of the 
last link will, therefore, result in an unreferenced file, which can 
be deleted by the "diskr epair " command. 
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ERRORS REPORTED 
EFLX 

The file <f ile_name_2> already exists. 

EISDR 

The file <f il e_name_l > is a directory, but the current effective 
user is not the system manager. 

EMSDR 

The path to either <f il e_name_l > or <f ile_name_2> or both cannot be 
followed. 

ENDR 

A part of the path to one or both of the specified files is not a 
directory. 

ENOFL 

No file on the system corresponds to <f il e_name_l> . 

EPRM 

Either the directory to contain the new link, <f ile_name_2> , does 
not grant write permission to the effective user, or the user does 
not have execute permission in all but the last component of both 
specified file names. 

EXDEV 

The specified files are not on the same device; therefore, the 
system cannot link them. 


SEE ALSO 
uni ink 

Commands: diskrepair, kill 
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lock 

Lock a task in memory or unlock a locked task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

lock,<function_code> 

Arguments 

<function_code> A number indicating the subfunction to 
perform. A nonzero value tells the operating 
system to lock the task in memory; a value of 
0, to unlock it. 


DESCRIPTION 

The "lock" system call locks a task in memory or unlocks a locked task. 
The operating system cannot take memory from a locked task to use for 
another task. 

Only the system manager may invoke this system call. 


NOTES 

. Unlocking a task that is not locked is not an error. 


ERRORS REPORTED 
EPRM 

The current effective user is not the system manager. 


SEE ALSO 
memman 
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lrec 

Add an entry to the operating system's lock table. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file__des> in DO 
Syntax Statement 

sys lrec,<count> 

Arguments 

<file__des> The file descriptor for the file containing the 
record to lock. 

<count> The number of bytes to lock from the current 

position in the file. 

DESCRIPTION 

The "lrec" system call adds to the operating system's lock table an 
entry for the open file referenced by <file__des>. If the current task 
already has an entry for that file descriptor in the system's lock 
table, "lrec" removes that entry. If another task has an entry for the 
file descriptor in the system's lock table, and that entry contains all 
or part of the record the current task is trying to lock, the system 
call fails. 

Locking a record only prevents other users from locking any of the data 
in that record. It does not prevent anyone from reading or modifying 
the record or any other part of the file. 

The operating system removes all entries a task makes in the lock table 
when the task terminates. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file, or it 
references a pipe, a character device, a block device, or a 
pseudoterminal . 

EBARG 

An argument to the system call is invalid. 
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ELOCK 

The specified record cannot be locked either because all or part of 
the record is already locked by another task or because the system's 
lock table is full. The system manager may use the "tune" command 
to alter the number of entries the lock table can contain. 


SEE ALSO 
urec 
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make_real time 

Make a non-real-time task a real-time task and set its relative 
priority, or make a real-time task a non-real-time task. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<relative_j>riority> in DO 
Syntax Statement 

sys make_jrealtime 
Arguments 

<relative__pr ior ity> A value used by the system scheduler to 

set the relative priority of a real-time 
task in case it must schedule the CPU 
among several real-time tasks. The 
value must be in the range of -25 to 25. 
The operating system ignores a value 
which is outside this range. A value of 
0 tells the system scheduler that the 
task is no longer a real-time task. 


DESCRIPTION 

The "make^realtime" system call either makes a non-real-time task a 
real-time task or makes a real-time task a non-real- time task. It also 
sets the priority of a real-time task in case the system scheduler must 
share the CPU among more than one real-time task. The priority of a 
real-time task is fixed by the "make__real time” or the "setpr" system 
call. Any real-time task has a higher priority than any non-real-time 
task. Only a real-time task of higher priority can usurp the CPU from a 
real-time task. 

If the system call is used to make a real-time task a non-real-time task 
(the user specifies a relative priority of 0), the operating system sets 
the priority of that task as it would normally. 

Only the system manager may invoke this system call. 
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NOTES 

. Real-time tasks are a vendor-dependent option and may not be 
supported by all systems. 

ERRORS REPORTED 
EBDCL 

The system does not support real-time tasks. 

EPRM 

The current effective user is not the system manager. 


SEE ALSO 

setpr 

yield_CPU 
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memman 

Perform a memory-management operation. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys memman, <f unct ion_code> ,<start_address> , <end_address> 

Arguments 

<f unction__code> The subfunction to perform. 

<start__address> The first address in the region of memory to 

control (but see DESCRIPTION). The value of 
<start_address> must be less than the value 
of <end__address) . 

<end_address> The last address in the region of memory to 

control (but see DESCRIPTION). The value of 
<end_address> must be greater than the value 
of <start__address) . 

DESCRIPTION 

The ,f meIImlan ,, system call performs a memory-management operation on the 
specified region of memory. It supports five subfunctions. The 
following table shows the function code associated with each of these 
functions. Some subfunctions, however, may not be available on a 
particular implementation. 

Code Subfunction 


0 Clear the region's "dirty bit". When set, the 
dirty bit tells the operating system that the copy 
of the page in the paging space is out of date. 

1 Lock the region in memory. 

2 Unlock the region from memory. 

3 Write protect the region. 

4 Remove write protection from the region. 

5 Release the memory allocated to the region. 

Regardless of the addresses specified, the region that the "memman" 
system call acts on is a set of pages. Each page contains 4K of memory. 
By default, the region ranges from the beginning of the page containing 
<start_address> to the end of the page containing <end__address> . For 

example, if the user specifies $1020 as <start_address> and $10A0 as 
<end_address>, "memman" acts on the region from $1000 through $1FFF 
inclusive. However, if the user adds 32 to the function code, the 
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region that "memman" acts on includes only those complete pages within 
the specified range. The addresses specified in the previous example do 
not encompass a complete page. Therefore, if the function code is in 
the range of 32 through 36 inclusive, they specify a null range. A 
<start_address> of $0040 and an <end_address> of $2FFF with a function 
code between 32 and 36 specify the region from $1000 through $2FFF 
inclusive. 


ERRORS REPORTED 


EBARG 

The function code is invalid; <start_address> is greater than 
<end_address>; or the address range specified by <start_address> and 
<end_address> is outside the task's address space. 

EVFORK 

The current task shares its memory with its parent and may not 
invoke this system call. 


SEE ALSO 
lrec 
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mount 

Insert the medium in the specified block device at the node of the 
directory tree specified by <dir_name>. 


ASSEMBLY LANGUAGE SYNTAX 


Syntax Statement 


sy s mount , <dev_name> , <d i rename > , <mode > 


Arguments 


<dev name> 


<di rename > 
<mode> 


The address of the null-terminated name of the 
device containing the medium to mount. The 
specified device must be a block device. 

The address of the nul 1-terminated name of the 
directory on which to mount the specified device. 
A value indicating whether or not to 
write-protect the mounted medium. A value of 0 
specifies to mount the medium for reading and 
writing; a nonzero value, for reading only. 


DESCRIPTION 

The ’’mount" system call temporarily inserts the medium in the specified 
block device at the node of the directory tree specified by <dir__name>. 
As long as the medium is mounted, any references to <dir_name> actually 
access the root directory of the mounted medium. If the medium is 
mounted for reading and writing, the "mount" function sets an indicator 
on the medium indicating that it is currently mounted. The "unmnt" 
system call clears this indicator. 

Any files in the directory on which the device is mounted are 
inaccessible for the duration of the mount. 

Only the system manager may invoke this system call. 


NOTES 

. Disks written by the "backup" command cannot be mounted. 


ERRORS REPORTED 
EBSY 

Either the operating system's mount table is full or something is 
already mounted on <dir_name>. 
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EDIRTY 

The last time the medium in the specified device was mounted, it was 
not properly unmounted. It may, therefore, be corrupt. The user 
should try to salvage the data by executing the "diskrepair" 
command. 

EFLX 

The medium in the specified device is already mounted. 

EIO 

The operating system cannot read the data on the medium in the 
specified device; no medium is in the specified device; or the 
medium is not correctly formatted. If "mount" returns this error 
when a properly formatted medium is in the device, the user should 
try to salvage the data on the medium by executing the "diskrepair" 
command. 

EMSDR 

The path to either <dev_name> or <dir_name> or both cannot be 
followed. 

ENBLK 

The specified device is not a block device. 

ENDR 

Either <dir_name> is not a directory or a part of the path to 
<dev_name> or <dir_name> is not a directory. 

ENOFL 

No file on the system corresponds to the specified name. 

EPRM 

The current effective user is not the system manager. 

EWRTPROT 

The specified device is write-protected. 

SEE ALSO 

crtsd 

unmnt 

Commands: backup, diskrepair 
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msg_attach 

Attach a task to a message exchange. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys msg_attach, <exchange_name> , <mode> 

Returns 

<exchange_JD> in DO 
Arguments 

<exchange___name> The 4-byte name of the message exchange to 

attach to the task. The name may contain 

any unique value, for example four ASCII 

characters. 

<mode> The access mode to use. A value of 0 

indicates that the task is to send messages 
to the exchange; a value of 1, that it is to 
receive messages from the exchange. The 

file "/lib/sysmessages" defines the 

following constants: 

Value Constant 


0 MS G_s e n d_mo d e 

1 MSG_receive_mode 

<exchange_ID> An identification number to associate* with 
this particular exchange. All other system 
calls referencing the exchange use this ID 
rather than the name of the exchange. 

DESCRIPTION 

A message exchange is a section of memory set aside as a repository for 
messages. Such exchanges allow intertask communication. An individual 
task can attach to no more than 32 message exchanges at the same time. 
The number of exchanges the system can support is system-dependent. The 
system manager can adjust this number within the permissible limits with 
the "tune" command. 
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The "msg attach” system call attaches a message exchange to the current 
task. The first attempt to attach to a nonexistent exchange in receive 
mode creates the exchange. The operating system does not allow a task 
to attach to a nonexistent exchange in send mode. 


NOTES 

. Message exchanges are a vendor-dependent option and may not be 
supported by all systems. 


ERRORS REPORTED 
EDFUL 

The operating system is already using the maximum permissible number 
of message exchanges. The system manager can alter this limit with 
the "tune" command up to the system-dependent maximum. 

ENOFL 

No message exchange on the system corresponds to the specified name, 
and the mode is MSG_Send_mode. 

ETMFL 

The task attempted to attach to more than 32 message exchanges at 
the same time. 


SEE ALSO 

msg detach 
msg send 
msg receive 
msg status 
Commands : tune 
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msg detach 

Detach a task from a message exchange. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<exchange_ID> in DO 
Syntax Statement 

sys msg detach 
Arguments 

<exchange_ID> The identification number of the exchange to 
detach from. This ID must be one returned 
from an "msg attach 11 system call. 

DESCRIPTION 

The lf msg detach* 1 system call detaches the task from a message exchange. 
After the last task attached to a message exchange has been detached 

from it, the exchange is released to the system. It may then be 

reallocated with the "msg attach 11 system call. 


NOTES 

. Message exchanges are a vendor-dependent option and may not be 
supported by all systems. 


ERRORS REPORTED 
EBADF 

The value of <exchange__ID> does not correspond to any message 
exchange which is attached to the task. 


SEE ALSO 

msg attach 
msg send 
msgreceive 
msg status 
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msg_receive 

Receive a message from another task via a message exchange. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<exchange_ID> in DO 
Syntax Statement 

sys msg_jreceive, <buf__add>,<mode> 

Arguments 

<exchange__ID> The identification number of the exchange from 
which to fetch a message. This ID must be one 
returned from an "msg attach 11 system call. 

<buf_add> The address of the buffer to receive the text 

of the message. This buffer should contain at 
least as many characters as are used for 
messages in the system. By default, the size 
of messages on any system is 64 bytes. The 
system manager can change this value with the 
"tune" command. 

<mode> The mode to use while fetching the message. A 

value of 0 tells the operating system to 
return an error if no messages are at the 
specified message exchange. A value of 1 
tells the operating system to suspend the 
receiving task until a message has been queued 
at the exchange. The file f, /lib/sysmessages n 
defines the following constants: 


Value Constant 


0 MSG_no_wa i t_f or_me s s a ge s 

1 MSG_wa i t_f or_me s sage s 


DESCRIPTION 

The ,f msg_receive M system call receives a message from another task via a 
message exchange. The operating system writes the first message in the 
queue associated with the specified exchange to the buffer at <buf_add>. 
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NOTES 

. Message exchanges are a vendor-dependent option and may not be 
supported by all systems. 

. Because the size of messages on any system is fixed, the operating 
system always moves the same number of bytes into the message 
buffer. If the buffer is not large enough to hold the message, the 
operating system simply writes past the end of the buffer, 
destroying any information located there. The destruction of such 
information could result in an address error, which would cause the 
program to abort. 


ERRORS REPORTED 
EBADF 

The value of <exchange_ID> does not correspond to any message 
exchange which is attached to the task. 

EINTR 

The task caught an interrupt, which caused the system call to end 
abnormally. 

ENOINPUT 

No messages are available at the exchange, and the task did not 
elect to wait for one. 


SEE ALSO 

msg attach 
msg detach 
msg send 
msg status 
Commands: tune 
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msg__send 

Send a message to another task via a message exchange. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<exchange_ID> in DO 
Syntax Statement 

sys msg_send,<buf__add>,<mode> 

Arguments 

<exchange__ID> The identification number of the exchange to 
which to send a message. This ID must be one 
returned from an n insg_ attach” system call. 
<buf_add> The address of the buffer containing the text 

of the message to send. This buffer should 
contain at least as many characters as are 
used for messages in the system. By default, 
the size of messages on any system is 64 
bytes. The system manager can change this 
value with the "tune” command. 

<mode> A 2-bit mask specifying the mode to use while 

sending the message. The following table 
shows the correspondence between the values of 
<mode> and the mode in which to operate. Any 
combination of bits is valid. 


Value 

Constant 

00 

MSG_no_wait 

01 

MSG__wait_f or__consumption 

10 

MS G_wa i t_f o r __s pace 


When MSG_no__wait mode is in effect, the 
operating system does not wait for a task to 
consume the message. Nor does it wait for 
space to send a message if the system is 
saturated with messages (rather, it returns an 
error). If MSG_wait_f or_consumpt ion is in 

effect, the operating system suspends the 
sending task until some other task consumes 
this particular message. If 

MSG_wait_f or_space is in effect, the operating 
system suspends the sending task until the 
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system is not saturated with messages. 

DESCRIPTION 

The Vsg^send" system call sends a message to another task via a message 
exchange. The operating system writes the text in the buffer at 
<buf_add> to the queue for the specified message exchange. 

The operating system limits the total number of messages that can be 
queued at all message exchanges. The system manager can adjust this 
limit with the "tune” command. A user can avoid this limit by invoking 
the command in MSG_wait_f or_space mode. 


NOTES 

. Message exchanges are a vendor-dependent option and may not be 
supported by all systems. 

. Because the size of messages on any system is fixed, the operating 
system always moves the same number of bytes from the beginning of 
the message buffer to the appropriate message exchange. If the 
buffer is not as large as this fixed size, the operating system 
simply uses information located past the end of the buffer. 
Obviously if such information is used, the latter part of the 
message will probably not make sense. 


ERRORS REPORTED 
EBADF 

The value of <exchange_ID> does not correspond to any message 
exchange which is attached to the task. 

EINTR 

The task caught an interrupt, which caused the system call to end 
abnormally. The operating system returns this error if a task 
invokes the system call when MSG_wait_for_con sumption or 
MSG_wait_for_space mode is in effect and receives an interrupt while 
it is waiting. In such a case the system call aborts with no ill 
effects. Thus, by using the waiting modes in conjunction with an 
alarm interrupt, the task may specify the maximum amount of time to 
wait. 

ENOINPUT 

The maximum number of messages allowed in all queues has been 
reached. The system manager can alter this limit with the "tune" 
command up to the system-dependent maximum. 
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ms 8-J attach 
msg_detach 
msg_receive 
msg_status 
Commands : tune 
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msg_status 

Obtain information about the status of a message exchange. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<exchange_ID> in DO 
Syntax Statement 

sys msg__status , <buf_add> 

Arguments 

<exchange__ ID> The identification number of the exchange to 

report on. This ID must be one returned from 
an !, msg_attach" system call. 

<buf__add> The address of the buffer to contain the 

information about the status of the message 
exchange. The buffer should contain at least 
MBX_STAT_SIZE characters, where MBX_STAT_SIZE 
is defined in the file "/lib/sysmessages". 

DESCRIPTION 

The "msg^status" system call obtains information about the status of a 
message exchange and writes that information to the buffer specified by 
<buf_add>. The information includes the name of the message exchange, 
the number of tasks currently attached to the exchange as senders, the 

number of tasks currently attached to the exchange as receivers, the 
number of messages in the queue, and the size of each message. 

The structure of this buffer is defined in the file "/lib/sysmessages" 
as follows: 


* Structure of buffer for status of exchange 
struct 0 

msg^jiame ds.l 1 Name of exchange 

msg_senders ds.w 1 Number of tasks attached as senders 

msg receivers ds.w 1 Number of tasks attached as receivers 

ms g_q_count ds.w 1 Number of messages in the queue 

msg_size ds.w 1 Size of each message on the system 

MBX STAT SIZE ds.w 0 


TSC 9/2/86 


(continued) 



msg status-2 


The size of all messages on a system is fixed, but varies from system to 
system because the system manager can adjust the size with the "tune" 
command. The ,f msg_status M system call returns the value of the size so 
that a task may adjust its buffers to conform to the value on the system 
in use. 


NOTES 

. Message exchanges are a vendor-dependent option and may not be 
supported by all systems. 


ERRORS REPORTED 
EBADF 

The value of <exchange__ID> does not correspond to any message 
exchange which is attached to the task. 


SEE ALSO 

msg attach 
msg_detach 
msg_receive 
msg_send 
Commands : tune 
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of stat 

Get the status of an open file. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 

sys of stat , <buf__add> 

Arguments 

<buf__add> The address of the buffer to contain the 
information on the status of the file. 

DESCRIPTION 

The "ofstat" system call writes to <buf_add> the information describing 
the status of the file referenced by <file_des>. The file 
M /lib/sysstat ,f defines the structure of this buffer as follows: 

* Definition of buffer for "status 11 and "ofstat" 

base 0 Set initial values 

st__dev ds.w 1 Device number 
st_fdn ds.w 1 Fdn number 
ds.b 1 Filler 
st_mod ds.b 1 File mode 
st_prm ds.b 1 Permission bits 
st_cnt ds.b 1 File link count 
st_own ds.w 1 File owner's user ID 
st_siz ds.l 1 File size in bytes 
stjmtm ds.l 1 Time of file's last modification 
st_spr ds.b 4 Spare — for future use only 

ST_SIZ ds.w 0 Size of status buffer 

The value "st_dev" is the device number of the device containing the 
file referenced by <file__des>; "st_fdn" is the file descriptor number 
(fdn) of the specified file. The variable "st_mod" is an 8-bit mask 
describing the type of the file; the low-order bit is ignored. The 
following table shows the valid values for this mask and the type of 
file associated with each value. The file "/lib/sysstat" defines the 
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constants whose names are shown in parentheses. 


st_mod Type of File 


OOOOOOOx Regular file (FSREG) 

OOOOOOlx Block device (FSBLK) 

OOOOOlOx Character device (FSCHR) 

OOOOlOOx Directory (FSDIR) 

lOOOOllx Master pseudoterminal (FSMPTY) 

OOOOOllx Slave pseudoterminal (FSSPTY) 

OlOOOOOx Pipe (FSPIPE) 


The variable "st_prm" is an 8-bit mask describing the access permissions 
for the file. The following table shows the type of permission that is 
associated with each bit in the mask. The file "/lib/sysstat" defines 
the constants whose names are shown in parentheses. Any combination of 
bits is valid. 


st_prm Permission Assigned 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 

01000000 


Owner read permission (FACUR) 

Owner write permission (FACUW) 

Owner execute permission (FACUE) 
Others read permission (FACOR) 
Others write permission (FACOW) 
Others execute permission (FACOE) 
Set user-ID bit for execute (FXSET) 


If the specified file is a directory, FACUE grants permissions to the 
user who owns the file to search the directory for the name of a file; 
FACOE grants the same permission to other users. When the user-ID bit 
is set, the operating system grants to any user who executes the file 
the same permissions as it grants to the owner of the file for the 
duration of the task. 


The value of "st_cnt" is the number of links to the specified file, or 
in the case of a pipe, the number of file descriptors open for the pipe; 
"st_own" is the user ID of the owner of the file; "st_siz" is the number 
of bytes in the file, or in the case a of a pipe, a flag indicating 
whether or not the pipe contains any data (if the file size of the pipe 
is 0, no data are in the pipe); "st_mtm" is the time (expressed as the 
number of seconds that had elapsed since midnight (00:00), January 1, 
1980) the file was last modified; "st_spr" is currently unused. 
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ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file. 
EBARG 

An argument to the system call is invalid. 

SEE ALSO 
status 
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open 

Open an existing file. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys open,<f ile_name> ,<mode> 

Returns 

<file_des> in DO 
Arguments 

<file_name> The address of the nul 1- terminated name to 
assign to the open file. 

<mode> A value which tells the operating system what 

sort of access to allow to the file. If <mode> 
is 0, the operating system opens the file for 
reading only; if 1, for writing only; if 2, for 
both reading and writing. If <file_name> 
references a character device, the user may add 
hexadecimal 8000 to this value to specify 
exclusive access. Exclusive access, which is 
only supported by some character devices, is 
useful, for example, in the case of a port that 
is used both as a terminal and for 

communications. 

<file_des> A number by which all other system calls must 
reference the open file. 

DESCRIPTION 

The "open" system call opens the specified file in the mode described by 
<mode>, sets the current file position to the beginning of the file, and 
assigns a file descriptor to the file. 

ERRORS REPORTED 
EBARG 

The value for <mode> is invalid. 

EMSDR 

The path to <file_name> cannot be followed. 
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ENDR 

A part of the path to <file_name> is not a directory. 

ENOFL 

No file on the system corresponds to the specified name. 

EPRM 

The file's access permissions do not grant the user the type of 
access requested by <mode>. 

ETMFL 

The current task already has open as many files as the operating 
system will allow. The system manager can alter this limit with the 
"tune" command up to the system-dependent maximum. 


SEE ALSO 

close 

create 

Commands : tune 
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phys 

Obtain or release access to a section of system memory. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys phys, [-] <code> 

Returns 

<log base add> in DO (only when obtaining access to memory) 
Arguments 

Release access to the specified section of 
memory. In the absence of a minus sign the 
system obtains access to the specified 
section of memory. 

<code> A number specifying the section of system 

memory to obtain or release access to. The 
correspondence between <code> and a 
particular system resource is part of the 
configuration of the system. A value of 0 
releases all sections of memory allocated by 
the current task through the "phys" system 
call. 

<log base add> The logical address of the base of a resource 
that is mapped into the task's address space. 

DESCRIPTION 

The "phys" system call accesses or releases the resource specified by 
<code>. If the specified resource has already been allocated by the 
task, "phys 11 ignores a request to allocate it. The system call also 
ignores any request to release a resource that has not been allocated to 
the task. 


ERRORS REPORTED 
EBARG 

The value of <code> is invalid. 

SEE ALSO 

Commands : tune 
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prof ile 

Start or stop monitoring the current task. 


ASSEMBLY LANGUAGE SYNTAX 


Syntax Statement 


sys prof ile, <s tar t__add> , <buf_add> , <size> , <scale> 


Arguments 


<start_add> 

<buf__add> 

<size> 

<scale> 


The address at which to begin monitoring the 
task. 

The address of the buffer to contain the results 
of the monitoring. 

The number of bytes in the buffer at <buf_add>. 
A number determining the granularity of the 
monitoring procedure. A value of 0 or 1 tells 
the operating system to stop monitoring the 
task. Other valid values are 2, 4, 8, 16, 32, 

64, and 128. If the user specifies an invalid 
value, profile 11 uses the largest valid value 
that does not exceed the specified value. 


DESCRIPTION 

The "profile 11 system call starts or stops monitoring the current task. 
If the value of <scale> is 0 or 1 , monitoring stops; otherwise, it 
begins. 

While monitoring a task the operating system examines the task at each 
tick of the system clock, which occurs every tenth of a second. If the 
program counter is at an address less than <star t__add> , the operating 
system does nothing; otherwise, it subtracts the value of <start_add> 
from the value of the current program counter, divides the result by 
<scale>, and multiplies the quotient by 2. If this product is less than 
<size>, the operating system adds its value to <buf_add> and increments 
the word at the resulting address by 1 . If the product is greater than 
<size>, no change is made in the buffer at <buf__add>. 


NOTES 

. The operating system automatically stops monitoring a task when that 
task invokes any "exec" system call, but not when it invokes the 
"fork" or "vfork" system call. 
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SEE ALSO 

exec 

exece 

fork 
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read 

Read data from an open file. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file__des> in DO 
Syntax Statement 

sys read, <buf_add> ,<count> 

Returns 

<by t es__read> ; " 

Arguments 

<file__des> The file descriptor of the open file to read. 

<buf__add> The address of the buffer to contain the data 

that are read. 

<count> The number of bytes to read. The system call 

performs more efficiently if this number is 
greater than 512 and less than 4,096 . 


DESCRIPTION 

The "read" system call reads data from the open file referenced by 
<file__des>. It begins reading at the current file position and 
continues until it has read <count> bytes, has reached the end of the 
file, or, if the specified file is a terminal, has read an end-of-line 
character. It writes the data it reads into the buffer located at 
<buf_add>. If the specified file is one that the user can randomly 
access, "read” sets the current file position to the byte immediately 
following the last byte read. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file, or the file is 
not open for- reading. 

EBARG 

The value for either <count> or <file des> is invalid. 
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EINTR 

The task received and caught an interrupt while the function was 
reading from a slow device. 

EIO 

The operating system returned an I/O error. In such a case the data 
in the buffer may not be the same as the data in the file. 


SEE ALSO 

create 

crpipe 

dup 

dups 

open 

write 
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rump 

Create, destroy, access, or relinquish access to a named resource. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<function_code> in DO 
<resource_name> in AO 

Syntax Statement 

sys rump 

Arguments 

<function_code> The subfunction to perform. 

<resource_jiame> The name of the resource to act on. It must 
be a null-terminated character string 
containing between 2 and 16 characters 
(including the null character). 

DESCRIPTION 

The "rump 1 * (resource utilization management protocol) system call 
provides a means of supplying exclusive access to physical resources 
such as I/O devices and special shared memory. It does so by allowing 
the user to create a named resource associated with a particular 
physical resource. The association is purely in the mind of the user. 
Because the operating system does not recognize the association between 
the physical resource and the named resource, any user who does not know 
of the existence of the named resource or who chooses to ignore its 
existence can access the device directly. All users should, therefore, 
be advised of the existence of any named resources so that they can 
honor the protocol of asking for access to those resources before using 
them. 

The number of named resources that a system can support is 
system-dependent . 

The "rump" system call supports four subfunctions. The following table 
shows the function code associated with each of these subfunctions: 
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Code Subfunction 

1 RUMP_ENQUEUE 

2 RUMP_DEQUEUE 

3 RUMP_CREATE 

4 RUMPJDESTROY 

A description of each of these subfunctions follows: 


RUMP_ENQUEUE 


RUMP_DEQUEUE 
RUMP_CREATE 
RUMP DESTROY 


Obtain exclusive access to the specified named 
resource. If another task currently has access 
to the resource, the operating system puts the 
calling task to sleep until the resource 
becomes available. If more than one task is 
waiting for access to a resource, the operating 
system provides access in the order in which 
the requests were made. 

Relinquish access to the specified named 
resource. 

Create a named resource. This subfunction does 
not provide access to the resource. 

Destroy the specified named resource. Any 
user, not only the user who created it, may 
destroy a resource. A resource cannot, 
however, be destroyed while any user has access 
to it. 


NOTES 

. Named resources are a vendor-dependent option and may not be 
supported by all systems. 


ERRORS REPORTED 
EBADF 

The user tried to relinquish access to a named resource but did not 
have access to the specified resource. 

EBSY 

The user tried to destroy a named resource, but the specified 
resource was in use. 

EDFUL 

The user tried to create a named resource, but the system is already 
supporting as many resources as it can. 
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EFLX 

The specified named resource already exists. 

EINTR 

The user tried to obtain access to a named resource, but the "rump” 
system call terminated abnormally. The operating system returns 
this error if a task invokes the RUMP_ENQUEUE subfunction on a busy 
resource and receives an interrupt while it is waiting for the 
resource. In such a case the subfunction aborts with no ill 
effects. Thus, by using the RUMP_ENQUEUE subfunction in conjunction 
with an alarm interrupt, the task may specify the maximum amount of 
time to wait for a busy resource. 

ENOFL 

The specified named resource does not exist. 
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sacct 

Enable or disable system accounting procedures. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys sacct, <file_name> 

Arguments 

<f ile__name> The address of the null-terminated name of the 
file to contain the data collected by the 
accounting process. The specified file must 
already exist. A null address ($0000) tells the 
operating system to disable the accounting 
procedures. 

DESCRIPTION 

The "sacct" system call enables or disables the system's accounting 
procedures. When the accounting procedures are enabled, the operating 
system appends a record to the specified file each time a task 
terminates. Each record is of the following structure, which is defined 
in the file "/lib/sysacct". A tick is one one-hundredth of a second. 


* Structure for accounting record 
struct 0 


acuid 

ds. b 

2 

User ID 

acstrt 

ds. b 

4 

Starting time of task 

acend 

ds. b 

4 

Ending time of task 

acsyst 

ds. b 

3 

System time used by task (in ticks) 

acusrt 

ds. b 

3 

User time used by task (in ticks) 

acstat 

ds.b 

2 

Termination status of task 

actty 

ds. b 

1 

Number of terminal where task originated 

acmem 

ds.b 

1 

Maximum memory used by task (4K blocks) 

acblks 

ds.b 

2 

I/O units used (measure of blocks read or written) 

acspar 

ds. b 

2 

Spare 

acname 

ds.b 

8 

Name of command executed by task 

AC_SIZ 

ds.b 

0 

Size of accounting record 


Only the system manager may invoke this system call. 
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ERRORS REPORTED 
EBADF 

The specified file is not a regular file. 

EFLX 

The system accounting procedures are already enabled. 
ENOFL 

No file on the system corresponds to the specified name. 
EPRH 

The current effective user is not the system manager. 
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seek 

Change the current file position of an open file. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 

sys seek,<count>,<pt_of_origin> 

Returns 

*■ i > * * * 

<new_position> ^ 

Arguments 5 

<file_des> The file descriptor of the file to 

reposition. 

<count> A four-byte, signed number specifying the 

number of bytes to shift the current file 
position from the point of origin (see 
following argument). 

<pt_of_origin> A value indicating where in the file to begin 
the specified shift. A value of 0 specifies 
the beginning of the file; of 1, the current 
position in the file; of 2, the end of the 
file. 

<new_position> The new current file position, which is 
expressed as the number of bytes beyond the 
beginning of the file. The first byte in the 
file is byte 0. 

DESCRIPTION 

The "seek" system call changes the current file position in the file 
referenced by <file_des>. If the specified position is beyond the 
current end of the file, the system sets the current file position 
accordingly, but does not actually allocate any new blocks if the file 
resides on a block device. A "read" system call returns null bytes for 
the data in the resulting gap in the file. 
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ERRORS REPORTED 
EBADF 

The file descriptor dots not reference an open file or the file is 
not open in the proper node* 

EBARG 

An argument to the system call is invalid. 

ESEEK 

Either the requested file position is before the beginning of the 
file or the file descriptor references a file which cannot be 
randomly accessed, such as e pipe# 


SEE ALSO 

create 

dup 

dups 

open 
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setpr 

Change the priority bias of the current task, 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<prior ity_bias> in DO 
Syntax Statement 
sys setpr 
Arguments 

<priority_bias> If the current task is a non-real-time task, 
<prior ity_bias> is a bias used by the system 
scheduler for scheduling the sharing of the 
CPU among several non-real-time tasks. If 
the task is a real-time task, 
<pr iority___bias> is a value used by the 
scheduler to set the relative priority of 
that task in case it must schedule the 
sharing of the CPU among several real-time 
tasks. In all cases the value of 
<pr ior ity_bias> must be in the range of -25 
to 25 inclusive. The operating system 
ignores a value which is outside this range. 
Only the system manager may use a negative 
number. 


DESCRIPTION 

The "setpr 11 system call changes the priority bias of the current 
non-real-time task or sets the priority of a real-time task. 

The priority of a non-real-time task may range from -128 to 127, with a 
task with a priority of -128 having the highest priority on the system; 
one with 127, the lowest. The system determines the priority by summing 
two values: a dynamic value, which it calculates based on what the task 
is currently doing, and a static value, the priority bias, which is 
initially 0. If the sum of these two components is less than -128, the 
operating system sets the priority to -128; if greater than 127, to 127. 
Two non-real-time tasks with the same priority alternate their use of 
the CPU. 
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The priority of a real-time task does not include a dynamic component; 
rather, it is fixed by the "setpr" or the "make_realtime" system call. 
Any real-time task has a higher priority than any non-real-time task. 
Only a real-time task of higher priority can usurp the CPU from a 
real-time task. 

ERRORS REPORTED 
EPRM 

The value specified for <priority_bias> is negative, but the current 
effective user is not the system manager. 


SEE ALSO 

make_realtime 

yield_CPU 
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s e t_h igh_ad dr e s s_mas k 

Load the specified value into the register for the hardware address 
mask. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<address_mask> in DO 
Syntax Statement 

sys set_high_address_mask 
Arguments 

<address_mask> A 32-bit value used to mask the high-order 
byte of all addresses from the 
microprocessor. The default is OxFFFFFFFF. 
The user must supply a 32-bit value, but only 
the high-order byte is significant. The 
operating system sets bits 0 through 23 
inclusive. 


DESCRIPTION 

The "set_high_address__mask" system call loads the specified value into 
the register for the hardware address mask. 

NOTES 

. The operating system supports the "set_high_address_mask" system 
call only on the Tektronix 4406. 
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spint 

Send an interrupt to a task. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<task_ID> in DO 
Syntax Statement 

sys spint ,< interrupt > 

Arguments 

<task_ID> The task ID of the task to interrupt. A value 

of 0 tells the operating system to send the 
interrupt to all tasks associated with the 
caller's controlling terminal. If <task__ID> is 
-1 and the current effective user is the system 
manager, the system sends the interrupt to all 
tasks on the system except 0 and 1, which are 
the scheduler and the initializer. 

<interrupt> The kind of interrupt to send (see table). 

DESCRIPTION 

The "spint” interrupt sends the specified interrupt to the task whose ID 
is <task_ID> if that task has the same effective user as the ta$k 
sending the interrupt or if the effective user of the calling task ’is 
the system manager. The file "/lib/sysints" defines the interrupts 
whose names are shown in the table accompanying this document. 

If not caught or ignored, the default behavior of each program interrupt 
(except SIGDEAD and SIGDUMP) is to terminate the task to which it is 
sent. As shown in the table, some also produce a "core dump". A core 
dump, which is a file in the working directory called "core", contains 
an image of the contents of the task's memory. Each byte in the program 
and stack space is written to a disk file immediately after receipt of 
the interrupt. The user can examine this file to determine the state of 
memory at the time the interrupt was received. A core dump is often 
useful for diagnostic purposes. The operating system will not create 
such a file. if the working directory contains a file named "core" which 
denies write permission to the current effective user or if the working 
directory denies write permission to the current effective user. 
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Table 1. Table of Interrupts 


Name 

Number 

Description 

A 

c 

D 

I 

R 

SIGHUP 

i 

Hangup 

+ 

+ 

- 

+ 

+ 

SIGINT 

2 

Keyboard 

+ 

+ 

- 

+ 

+ 

SIGQUIT 

3 

Quit 

+ 

+ 

+ 

+ 

+ 

SIGEMT 

4 

A-line (Axxx) emulation trap 

+ 

+ 

+ 

+ 

+ 

SIGKILL 

5 

Task kill 

+ 

- 

- 

- 

+ 

SIGPIPE 

6 

Broken pipe 

+ 

+ 

- 

+ 

+ 

SIGSWAP 

7 

Swap error 

+ 

+ 

- 

- 

+ 

SIGTRACE 

8 

Trace 

+ 

+ 

- 

+ 

- 

SIGTIME 

9 

Time limit 

+ 

+ 

+ 

- 

+ 

SIGALRM 

10 

Alarm 

+ 

+ 

- 

+ 

+ 

SIGTERM 

11 

Task terminate 

+ 

+ 

- 

+ 

+ 

SIGTRAPV 

12 

TRAPV instruction 

+ 

+ 

+ 

+ 

+ 

SIGCHK 

13 

CHK instruction 

+ 

+ 

+ 

+ 

+ 

SIGEMT2 

14 

F-line (Fxxx) emulation trap 

+ 

+ 

+ 

+ 

+ 

SIGTRAP1 

15 

TRAP #1 instruction 

+ 

+ 

+ 

+ 

+ 

SIGTRAP2 

16 

TRAP #2 instruction 

+ 

+ 

+ 

+ 

+ 

SIGTRAP3 

17 

TRAP #3 instruction 

+ 

+ 

+ 

+ 

+ 

SIGTRAP4 

18 

TRAP # 4 instruction 

+ 

+ 

+ 

+ 

+ 

SIGTRAP5 

19 

TRAP #5 instruction 

+ 

+ 

+ 

+ 

+ 

SIGTRAP6 

20 

TRAP #6-14 instruction 

+ 

+ 

+ 

+ 

+ 

SIGPAR 

21 

Parity error 

+ 

+ 

+ 

- 

+ 

SIGILL 

22 

Illegal instruction 

+ 

+ 

+ 

- 

+ 

SIGDIV 

23 

Division by 0 

+ 

+ 

+ 

+ 

+ 

SIGPRIV 

24 

Privileged instruction 

+ 

+ 

+ 

- 

+ 

SIGADDR 

25 

Address error 

+ 

+ 

+ 

- 

+ 

SIGDEAD 

26 

A child task terminated 

- 

+ 

- 


+ 

SIGWRIT 

27 

Write to read-only memory 

+ 

+ 

+ 

- 

+ 

SIGEXEC 

28 

Data or stack space violation 

+ 

+ 

+ 

- 

+ 

SIGBND 

29 

Segmentation violation 

+ 

+ 

+ 

- 

+ 

SIGUSR1 

30 

User-defined interrupt #1 

+ 

+ 

- 

+ 

+ 

SIGUSR2 

31 

User-defined interrupt #2 

+ 

+ 

- 

+ 

+ 

SIGUSR3 

32 

User-defined interrupt #3 

+ 

+ 

- 

+ 

+ 

SIG ABORT 

33 

Program abort 

+ 

- 

- 

- 

+ 

SIGSPLR 

34 

Spooler signal 

+ 

+ 

- 

+ 

+ 

SIGINPUT 

35 

Input is ready 

+ 

+ 

- 

+ 

+ 

SIGDUMP 

36 

Take memory dump 

0 

+ 

+ 

+ 

+ 


37-41 

System-defined interrupts 






SIG UNORDERED 

42 

MC68881 branch or set on 
unordered operand 

+ 

+ 


+ 

+ 

SIG INEXACT 

43 

MC68881 inexact result 

+ 

+ 

- 

+ 

+ 

SIGFPDIVIDE 

44 

MC68881 division by 0 

+ 

+ 

- 

+ 

+ 

SIGUNDERFLOW 

45 

MC68881 underflow 

+ 

+ 

- 

+ 

+ 

SIG OPERAND 

46 

MC68881 invalid operand 

+ 

+ 

- 

+ 

+ 

SIGOVERFLOW 

47 

MC68881 overflow 

+ 

+ 

- 

+ 

+ 

SIGSNAN 

48 

MC68881 signaling not-a-number 

+ 

+ 

- 

+ 

+ 


49-63 

Vendor-defined interrupts 







Notes: A = Default state is "abort" (otherwise, "ignore") 

C = Interrupt can be caught 
D = Produces a core dump 
I = Interrupt can be ignored 
R = Resets to default state when triggered 
0 = See text 
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The default action for the SIGDUMP interrupt is to create a core dump 
and return control to the task. The task is not terminated. 

A vendor may use a TRAP instruction with a number greater than 6. In 
such a case the user should not issue the instruction. 

User-defined interrupts are available to the end user. 


NOTES 

. A controlling terminal is normally the terminal that started the 
task or one of the task's ancestors. A task can change its 
controlling terminal by closing all files that refer to terminals 
and then opening a terminal device. This device becomes the 
controlling terminal. 

. The SIGTIME interrupt is not currently implemented. 


ERRORS REPORTED 
EBARG 

The value of <interrupt> is not a valid interrupt number. 

ENTSK 

The value of <task_ID> is not a valid task ID. 

EPRM 

The current effective user is neither the system manager nor the 
current effective user of the specified task. 


SEE ALSO 
cpint 
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stack 

Extend the stack space of the current task. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<address> in AO 
Syntax Statement 
sys stack 
Arguments 

<address> The address to which to extend the stack. If 
<address> is greater than the address that is 
currently the end of the stack, the task 

relinquishes to the operating system all memory up 
to and including <address>. 


DESCRIPTION 

The "stack" system call extends the stack space of the current task. 
Initially the operating system assigns between 100 and 3,000 bytes to 
the stack, depending on the number of arguments passed with the "exec" 
system call. 


ERRORS REPORTED 
ESTOF 

The stack space of the current task is as large as it can get. The 
user can change the maximum size of the program with the "headset" 
command. 

EVFORK 

The current task shares its memory with its parent and may not 
invoke this system call. 


SEE ALSO 
break 

Commands: headset 
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stack_limit 

Specify a limit to the task's stack segment. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<address> in AO 
Syntax Statement 

sys stack__limit 
Returns 

<previous__limit > in DO 
Arguments 

<address> The desired lowest address for the stack. 

The operating system truncates the 
specified value to the address of the 
first byte in the page containing 
<address>. Specifying an address of 0 
removes the limit on the size of the 
stack. If the specified address is in a 
page that is higher than the page 
currently referenced by the stack 
pointer, the operating system immediately 
sends the task a SIGEXEC interrupt. 
<previous_J.imit> The value of the previous stack limit. 

The system call returns 0 if no previous 
stack limit was in effect. 


DESCRIPTION 

The "stack^limit" system call sets a lower limit on the growth of the 
program's stack segment. The specified value is truncated to the lowest 
address in the page. If the operating system attempts to allocate a 
page of memory for the stack which is below the limit, the memory is not 
allocated and a SIGEXEC interrupt is sent to the task. 


NOTES 

. The operating system checks the stack limit only when processing the 
"stack” system call or expanding the task's logical address space as 
part of the automatic growth of the stack. If the memory page 
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immediately below the stack limit is already part of the task's 
logical address space the limit is checked only when processing the 
"stack" system call. If the user is raising the stack limit, it is 
good programming practice to issue a "stack" system call with the 
same argument as passed to the "stack_limit" system call in order to 
remove those stack pages that are below the stack limit from the 
task's logical address space. 


ERRORS REPORTED 
EBARG 

The specified address is larger than the maximum valid value for the 
stack. 


SEE ALSO 
stack 
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status 

Get the status of a file. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys status, <f il e_name> , <buf_add> 

Arguments 

<file_name> The address of the null-terminated name of the 
file to examine. 

<buf__add> The address of the buffer to contain the 
information on the status of the file. 


DESCRIPTION 

The "status" system call writes to <buf__add> the information describing 
the status of the file referenced by <f ile__name>. The file 

"/lib/sysstat" defines the structure of this buffer as follows: 

* Definition of buffer for "status" and "ofstat" 

base 0 Set initial values 

st_dev ds.w 1 Device number 
st_fdn ds.w 1 Fdn number 
ds.b 1 Filler 
st_mod ds.b 1 File mode 
st_prm ds.b 1 Permission bits 
st__cnt ds.b 1 File link count 
st_own ds.w 1 File owner's user ID 
st_siz ds.l 1 File size in bytes 
st_mtm ds.l 1 Time of file's last modification 
st_spr ds.b 4 Spare — for future use only 

ST_J>IZ ds.w 0 Size of status buffer 

The value of "st__dev" is the device number of the device containing the 
file referenced by <file__des>; "st__fdn" is the file descriptor number 
(fdn) of the specified file. The variable "st_mod" is an 8-bit mask 
describing the type of the file; the low-order bit is ignored. The 
following table shows the valid values for this mask and the type of 
file associated with each value. The file "/lib/sysstat" defines the 
constants whose names are shown in parentheses. 
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st_mod Type of File 


OOOOOOOx 

OOOOOOlx 

OOOOOlOx 

OOOOlOOx 

lOOOOllx 

OOOOOllx 

OlOOOOOx 


Regular file (FSREG) 

Block device (FSBLK) 

Character device (FSCHR) 
Directory (FSDIR) 

Master pseudoterminal (FSMPTY) 
Slave pseudoterminal (FSSPTY) 
Pipe (FSPIPE ) 


The variable "st_prm" is an 8-bit mask describing the access permissions 
for the file. The following table shows the type of permission that is 
associated with each bit in the mask. The file "/lib/sysstat" defines 
the constants whose names are shown in parentheses. Any combination of 
bits is valid. 


st_prm Permission Assigned 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 

01000000 


Owner read permission (FACUR) 

Owner write permission (FACUW) 

Owner execute permission (FACUE) 
Others read permission (FACOR) 
Others write permission (FACOW) 
Others execute permission (FACOE) 
Set user-ID bit for execute (FXSET) 


If the specified file is a directory, FACUE grants permissions to the 
user who owns the file to search the directory for the name of a file; 
FACOE grants the same permission to other users. When the user-ID bit 
is set, the operating system grants to any user who executes the file 
the same permissions as it grants to the owner of the file for the 
duration of the task. 


The value of "st_cnt" is the number of links to the specified file; 
"st_own" is the user ID of the owner of the file; "st_siz" is the number 
of bytes in the file; "st_mtm" is the time (expressed as the number of 
seconds that had elapsed since midnight (00:00), January 1, 1980) the 
file was last modified; M st_spr" is currently unused. 


ERRORS REPORTED 
EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 
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ENOFL 

No file on the system corresponds to the specified name. 

SEE ALSO 
of stat 
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stime 


Set the system date and time. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<time> in DO 
Syntax Statement 
sys stime 
Arguments 

<time> The number of seconds that have elapsed since 
midnight (00:00), January 1, 1980, at the zeroth 

meridian (Greenwich, England). 

DESCRIPTION 

The "stime" system call sets the system time and date to the value 
specified by <time>. 

Only the system manager may invoke this system call. 


NOTES 

. The operating system converts <time> to the system time based on its 
perception of the time zone, which by default is 300 minutes west of 
Greenwich, England. The system manager may use the "tune" command 
to alter the time zone. 


ERRORS REPORTED 
EPRM 

The current effective user is not the system manager. 


SEE ALSO 

Commands: date, tune 
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Suspend the current task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys stop 


DESCRIPTION 

The "stop" system call suspends the current task indefinitely. The 
system call returns only if the task receives an interrupt, catches it, 
and returns from the interrupt-handling routine. If "stop" does return, 
it always returns the error EINTR. 


ERRORS REPORTED 


EINTR 

If the "stop” system call returns, it returns this error. 

SEE ALSO 

alarm 

cpint 

spint 
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suid 

Set both the user ID and the effective user ID. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<user_ID> in DO 
Syntax Statement 
sys suid 
Arguments 

<user_ID> The user ID to assign to both the user and the 
effective user. 


DESCRIPTION 

The "suid n system call sets the user ID of both the user and the 
effective user. At the time the task invokes the system call, either 
the user or the effective user must be the system manager. 


ERRORS REPORTED 
EPRM 

Neither the user nor the effective user is the system manager. 


SEE ALSO 
guid 
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term 

Terminate the current task, 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<term__status> in DO 
Syntax Statement 
sys term 
Arguments 

<term_status> The termination status to assign to the task 
as it terminates. A nonzero status should 
indicate an error. 

DESCRIPTION 

The "term 11 system call terminates the current task. It never returns to 
the caller. The termination status is available to the parent task 
through the "wait" system call. 

SEE ALSO 
wait 
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time 

Get the system time and other related parameters. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys time, <buf__add> 

Arguments 

<buf_add> The address of the buffer to contain the 
information obtained by the system call. 


DESCRIPTION 

The "time" system call returns the system time and several related 
parameters to the specified buffer. The file n /lib/syst im" defines the 
structure of the buffer at <buf add> as follows; 


* Buffer for " time" 
base 0 


tm_sec ds.l 1 
tm_tik ds.b 1 
tmjist ds.b 1 
tm zon ds.w 1 


Time in seconds since 00:00, January 1, 1980 
Number of ticks into the current second 
Flag for Daylight Savings Time 
Time zone 


TM SIZ ds.w 0 


Size of buffer 


The operating system stores the time as a 4-byte value, "tm__sec", which 
represents the number of seconds that have elapsed since midnight 
(00:00), January 1, 1980, at the zeroth meridian (Greenwich, England). 
The value in "tm_tik" represents the number of ticks that had passed in 
the current second when the system call was invoked. Each tick 
represents one one-hundredth of a second. 


The Daylight Savings Time flag, n tm_dst ,f indicates whether or not 
Daylight Savings Time is observed locally. A value of 0 indicates that 
it is not; a value of 1, that it is. The default value is 0. The 
operating system assumes that Daylight Savings Time begins and ends 
according to the dates used in the United States — the last Sunday in 
April and the last Sunday in October. The system manager may alter the 
value of ,f tm dst" with the "tune” command. 
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The value stored in M tm__zon" represents the time difference in minutes 
between local time and Universal Time, A positive value of "tinjzon" 
indicates the number of minutes west of Greenwich, England; a negative 
value, the number of minutes east. The default value is 300. The 
system manager may alter the value of ,, tm_zon n with the ,f tune M command. 

SEE ALSO 

Commands: tune 
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truncate 


Set the size of an open file. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 
sys truncate 
Arguments 

<file__des> The file descriptor of the file whose size to 
alter. It must reference a regular file. 


DESCRIPTION 

The "truncate" system call sets the size of the file referenced by 
<file__des> so that its end-of-file is the current file position. The 
file must be open for writing. If the current file position is before 
the existing end-of-file, the system call truncates the file. If the 
current file position is beyond the existing end-of-file, the system 
call extends the file. When "truncate" extends a file, it does not 
actually allocate any new blocks if the file resides on a block device. 
A "read" system call returns null bytes for the data in the resulting 
gap in the file. 


NOTES 

. If <file_des> references a device or a pipe, the "truncate" system 
call does nothing. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file, or the file is 
not open for writing. 

EBARG 

An argument to the system call is invalid. 
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EISDR 

The file referenced by <file_des> is a directory. 

SEE ALSO 
seek 
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ttime 

Get the information on the use of the CPU by the current task and its 
child tasks. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys ttime, <buf__add> 

Arguments 

<buf_add> The address of the buffer to contain the 
information obtained by the system call. 


DESCRIPTION 

The "ttime" system call obtains information about the use of the central 
processing unit (CPU) by the current task, by the operating system on 
behalf of the current task, by all child tasks, and by the operating 
system on behalf of all child tasks. The operating system continuously 
updates the information about usage of the CPU by the current task and 
by the operating system on behalf of the current task. It updates the 
information about usage of the CPU by child tasks and by the operating 
system on behalf of all child tasks whenever a child task terminates. 

The following table shows the structure of the buffer at <buf__add> as 
defined in the file ,r /lib/syst im". All numbers represent ticks. A tick 
is one one-hundredth of a second. 


* Buffer for ,, ttime M 


base 0 


ti_usr 

ds. 1 

1 

CPU use 

by 

current task 



ti_sy s 

ds. 1 

1 

CPU use 

by 

system on behalf 

of 

current task 

ti_chu 

ds. 1 

1 

CPU use 

by 

all descendants 

of 

current task 

ti_chs 

ds. 1 

1 

CPU use 

by 

system on behalf 

of 

all descendants 

TM SIZ 

ds . w 

0 

Size of 

buffer for "ttime" 




SEE ALSO 

fork 

vfork 
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ttyget 

Get information on the configuration of a terminal. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 


sy s ttyget , <buf__add> 
Arguments 


<f ile_des> 

The file descriptor of 
the terminal to examine. 

the file associated 

with 

<buf__add> 

The address of 

the 

buffer to contain 

the 


information about 
specified terminal. 

the 

configuration of 

the 

DESCRIPTION 






The "ttyget" system call obtains information about the configuration of 
the terminal referenced by <file_des> and writes that information into 
the buffer at <buf__add>. The file " / lib /syst ty " defines the structure 
of this buffer as follows: 


* Definition of buffer for "ttyset" and "ttyget" 
base 0 


ttJElg 

ds.b 

i 

Flags 

tt_dly 

ds. b 

i 

Delays 

tt_ cnc 

ds. b 

i 

Line-cancel character (default is control-X) 

t t__bks 

ds. b 

i 

Backspace character (default is control-H) 

tt_spd 

ds. b 

i 

Terminal speed 

tt_spr 

ds. b 

i 

Stop output byte 

TT__SIZ 

ds . w 

0 

Size of buffer 

The information 

contained in the first byte of the buffer, "tt_flg", 

describes the 

t way 

in 

which the terminal handles input and output. The 


following table shows the type of behavior governed by each bit. The 
file f, /lib/systty 11 defines the constants whose names are shown in 
parentheses. Any combination of bits is valid. 
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Bit Pattern Behavior 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 

01000000 

10000000 


Raw I/O mode (RAW) 

Echo input (ECHO) 

Expand tabs on output (XTABS) 

Map upper- to lowercase (LCASE) 
Automatic line-feed (CRMOD) 

Echo backspace-echo character (BSECH) 
Single-character input mode (SCHR) 
Ignore control characters 


These modes are described in detail in Section 6.2 of the 68xxx UniFLEX 
Programmer 's Guide . 


The information contained in the second byte of the buffer, "tt_dly", 
defines the length of the delay the system uses after outputting a 
new-line character, a carriage return, a tab character, a vertical tab 
character, or a form-feed character. A delay is useful in cases where a 
slow output device such as a teleprinter, which requires a delay for 
carriage returns, is attached to the system. The following table shows 
the kind of delay implemented by each bit. Any combination of bits is 
valid although the system ignores bits 6 and 7. 


Bit Pattern 

Kind of Delay Affected 

Length of Delay (msec) 

00000001 

New- line 

10 

00000010 

New-line 

20 

00000100 

Carriage return 

10 

00001000 

Carriage return 

20 

00010000 

Tab 

20 

00100000 

Vertical tab 

240 


The file M /lib/systty" defines certain combinations of bits in the delay 
byte as follows: 


Bit Pattern 

Constant 

Kind of Delay 

Length of Delay (msec) 

00000011 

DELNL 

New- line 

30 

00001100 

DELCR 

Carriage return 

30 

00010000 

DELTB 

Tab 

20 

00100000 

DELVT 

Vertical tab 

240 

00100000 

DELFF 

Form-feed 

240 

third and 

fourth byt 

es of the buffer 

define the line-cancel and 


backspace characters. The default line-cancel character is control-X; 
the default backspace, control-H. 
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The fifth byte of the "ttyset" buffer is the terminal speed byte. This 
byte presently implements only four bits. Bits 2, 3, and 4 define the 
configuration of the terminal; bit 7 is a flag which, when set, 
indicates that the terminal has input characters waiting to be consumed 
by the program. This bit is only meaningful when read — that is, the 
input-ready condition should not be set with the "ttyset" system call. 
A picture of this byte follows. The file "/lib/systty" defines the 
constant INCHR. 


Terminal speed byte (tt_spd): 


! 7 ! 6 ! 5 ! 4 ! 3 ! 2 ! 1 ! 0 ! 

!!!!!!!! 

!!!!!!! spare 

!!!!!! spare 

! ! ! ! ! first bit of terminal configuration 

! ! ! ! second bit of terminal configuration 

! ! ! third bit of terminal configuration 

! ! spare 

| spare 

input ready to be consumed (INCHR) 

Under normal input operations the "input ready to be consumed" bit does 

not come on until an entire line has been input and terminated by a 
carriage return. There are special input modes which can be 
established, however, where the "input ready to be consumed" bit will 
come on as soon as a single character is input. These modes, "raw I/O 
mode" and "single character input mode" are described in Section 6.2 of 
the 6 8 xxx UniFLEX Programmer ^ s Guide . 

The following table shows the configuration of the terminal for all 
possible settings of the terminal configuration bits: 


Terminal Configuration Data Bits Stop Bits Parity 

(Bit Pattern) 


0 0 0 
0 0 1 
0 10 
0 1 1 
1 0 0 
1 0 1 
1 1 0 
1 1 1 


7 

7 

7 

7 

8 
8 
8 
8 


2 

2 

1 

1 

2 

1 

1 

1 


Even 

Odd 

Even 

Odd 

None 

None 

Even 

Odd 


TSC 9/2/86 


(continued) 



ttyget-4 


The last byte in the "ttyset" buffer is the stop output byte, which 
defines the baud rate and which characters may be used to stop and start 
output, A user may stop and start output to a terminal by one of two 
methods: using the escape key or using XON/XOFF processing. 

The escape key method permits a user to type an escape character 
(hexadecimal IB) to stop output, A subsequent escape character restarts 
the output. The XON/XOFF method permits a user to type an XOFF 
character (hexadecimal 13) to stop output and a subsequent XON character 
(hexadecimal 11) to restart it. Many terminals produce XON and XOFF 
characters automatically to prevent the computer from sending too many 
characters to the terminal at once. The escape and XON/XOFF mechanisms 
can be independently enabled or disabled by setting or clearing the 
appropriate bits in the byte M tt_spr l *. A picture of the byte follows. 
The file "/lib/systty" defines the constants whose names are shown in 
parentheses. 


Stop output byte (tt_spr): 


! 7 ! 6 ! 5 ! 4 ! 3 ! 2 ! 1 ! 0 ! 


first bit of baud rate 
second bit of baud rate 
third bit of baud rate 
fourth bit of baud rate 
spare 

any character restarts output (XANY) 
enable XON/XOFF for output (XONXOF) 
disable escape for output (ESCOFF) 

If XANY is in effect, the terminal drivers restart output stopped by 
either an escape or an XOFF character when the user types any character. 

The following table shows the baud rate defined by all possible settings 
of the first four bits of the stop output byte: 


! ! ! ! ! 
!!!!-. 

! ! ! 

! j 

t 


Bit Pattern Baud Rate Bit Pattern Baud Rate 


0 

0 

0 

0 

— 

1 

0 

0 

0 

1200 

0 

0 

0 

1 

75 

1 

0 

0 

1 

1800 

0 

0 

1 

0 

110 

1 

0 

1 

0 

,2400 

0 

0 

1 

1 

134.5 

1 

0 

1 

1 

3600 

0 

1 

0 

0 

150 

1 

1 

0 

0 

4800 

0 

1 

0 

1 

200 

1 

1 

0 

1 

7 200 

0 

1 

1 

0 

300 

1 

1 

1 

0 

9600 

0 

1 

1 

1 

600 

1 

1 

1 

1 

19200 
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Not all hardware supports all of these baud rates, and not all hardware 
allows the dynamic changing of baud rates. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file. 

EBARG 

An argument to the system call is invalid. 

ENTTY 

The file referenced by <file_des> is not a character device. 


SEE ALSO 
ttyset 

6 8 xxx UniFLEX Programmer 's Guide 


TSC 9/2/86 




ttynum-1 


t tynum 

Get the terminal number of the task's controlling terminal. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys ttynum 
Returns 

<tty_num> in DO 
Arguments 

<tty_num> The number of the task's controlling terminal. 

The controlling terminal is normally the terminal 
that started the task or one of the task's 
ancestors. A task can change its controlling 
terminal by closing all files that refer to 
terminals and then opening a terminal device. 
This device becomes the controlling terminal. 


DESCRIPTION 

The "ttynum" system call returns the number of the task's controlling 
terminal. If the task has no controlling terminal (standard input, 
standard output, and standard error are all closed), the system call 
returns 0. Of course, "ttynum" also returns 0 if the controlling 
terminal is "/dev/ttyOO", the console. It is impossible to distinguish 
between these two cases. 
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tty set 

Set the configuration of a terminal. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file__des> in DO 
Syntax Statement 

sys tty set , <buf__add> 

Arguments 

<file_des> The file descriptor of the file associated with 
the terminal to alter. 

<buf_add> The address of the buffer containing the 
information about how to set the configuration of 
the specified terminal. 

DESCRIPTION 

The "ttyset" system call reads the information in the buffer at 
<buf___add> and changes the configuration of the terminal referenced by 
<file__des> accordingly. Normally, the user should invoke the "ttyget" 
system call prior to the "ttyset” system call in order to obtain 
information about the current configuration of the terminal. The 
desired bits should be set or cleared using the logical operators "and” 
and "or". The file "/lib/systty" defines the structure of this buffer 
as follows: 

* Definition of buffer for "ttyset" and "ttyget" 
base 0 

tt_flg ds.b 1 Flags 
tt_dly ds.b 1 Delays 

tt__cnc ds.b 1 Line-cancel character (default is control-X) 
tt_bks ds.b 1 Backspace character (default is control-H) 
tt_spd ds.b 1 Terminal speed 
tt_spr ds.b 1 Stop output byte 

TT_SIZ ds.w 0 Size of buffer 

The information contained in the first byte of the buffer, "tt__flg", 
describes the way in which the terminal handles input and output. The 
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following table shows the type of behavior governed by each bit. The 
file "/lib/systty" defines the constants whose names are shown in 
parentheses. Any combination of bits is valid. 


Bit Pattern Behavior 


00000001 

00000010 

00000100 

00001000 

00010000 

00100000 

01000000 

10000000 


Raw I/O mode (RAW) 

Echo input (ECHO) 

Expand tabs on output (XTABS) 

Map upper- to lowercase (LCASE) 
Automatic line-feed (CRM0D) 

Echo backspace-echo character (BSECH) 
Single-character input mode (SCHR) 
Ignore control characters 


These modes are described in detail in Section 6.2 of the 68xxx UniFLEX 
Programmer ^ Guide . 

The information contained in the second byte of the buffer, "tt_dly", 
defines the length of the delay the system uses after outputting a 
new-line character, a carriage return, a tab character, a vertical tab 
character, or a form-feed character. A delay is useful in cases where a 
slow output device such as a teleprinter, which requires a delay for 
carriage returns, is attached to the system. The following table shows 
the kind of delay implemented by each bit. Any combination of bits is 
valid although the system ignores bits 6 and 7. 


Bit Pattern Kind of Delay Affected Length of Delay (msec) 


00000001 New- line 10 
00000010 New-line 20 
00000100 Carriage return 10 
00001000 Carriage return 20 
00010000 Tab 20 
00100000 Vertical tab 240 


The file "/lib/systty" defines certain combinations of bits in the delay 
byte as follows: 


Bit Pattern Constant Kind of Delay Length of Delay (msec) 


Q000001L 

DELNL 

New-line 

30 


00001100 

DELCR 

Carriage return 

30 


00010000 

DELTB 

Tab 

20 


00100000 

DELVT 

Vertical tab 

240 

" 

00100000 
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The third and fourth bytes of the buffer define the line-cancel and 
backspace characters. The default line-cancel character is control-X; 
the default backspace, control-H. 

The fifth byte of the "ttyset" buffer is the terminal speed byte. This 
byte presently implements only four bits. Bits 2, 3, and 4 define the 
configuration of the terminal; bit 7 is a flag which, when set, 
indicates that the terminal has input characters waiting to be consumed 
by the program. This bit is only meaningful when read — that is, the 
input-ready condition should not be set with the "ttyset" system call. 
A picture of this byte follows. 


Terminal speed byte (tt_spd): 


! 7 ! 6 ! 5 ! 4 ! 3 ! 2 ! 1 ! 0 ! 


i i i i t i t i 

!!!!!!! spare 

!!!!!! spare 

! ! ! ! ! first bit of terminal configuration 

! ! ! ! second bit of terminal configuration 

j j t third bit of terminal configuration 

! ! spare 

t spare 

Cannot be set by the user 

Under normal input operations the "input ready to be consumed" bit does 
not come on until an entire line has been input and terminated by a 
carriage return. There are special input modes which can be 
established, however, where the "input ready to be consumed" bit will 
come on as soon as a single character is input. These modes, "raw I/O 
mode" and "single character input mode" are described in Section 6.2 of 
the 6 8 xxx UniFLEX Programmer 's Guide . 

The following table shows the configuration of the terminal for all 
possible settings of the terminal configuration bits: 


Terminal Configuration Data Bits Stop Bits Parity 

(Bit Pattern) 


0 0 0 
0 0 1 
0 1 0 
0 1 1 
1 0 0 
1 0 1 
1 1 0 
1 1 1 


7 

7 

7 

7 

8 
8 
8 
8 


2 

2 

1 

1 

2 

1 

1 

1 


Even 

Odd 

Even 

Odd 

None 

None 

Even 

Odd 
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The last byte in the "ttyset" buffer is the stop output byte, which 
defines the baud rate and which characters may be used to stop and start 
output. A user may stop and start output to a terminal by one of two 
methods: using the escape key or using XON/XOFF processing. 

The escape key method permits a user to type an escape character 
(hexadecimal IB) to stop output. A subsequent escape character restarts 
the output. The XON/XOFF method permits a user to type an XOFF 
character (hexadecimal 13) to stop output and a subsequent XON character 
(hexadecimal 11) to restart it. Many terminals produce XON and XOFF 
characters automatically to prevent the computer from sending too many 
characters to the terminal at once. The escape and XON/XOFF mechanisms 
can be independently enabled or disabled by setting or clearing the 
appropriate bits in the byte "tt^spr". A picture of the byte follows. 
The file ,, /lib/systty M defines the constants whose names are shown in 
parentheses. 


Terminal output byte (tt__spr): 


! 7 ! 6 ! 5 ! 4 ! 3 ! 2 ! 1 ! 0 ! 


first bit of baud rate 
second bit of baud rate 
third bit of baud rate 
fourth bit of baud rate 
spare 

any character restarts output (XANY) 
enable XON/XOFF for output (XONXOF) 
disable escape for output (ESCOFF) 

When XANY is in effect, the terminal drivers restart output stopped by 
either an escape or an XOFF character when the user types any character. 

The following table shows the baud rate defined by all possible settings 
of the first four bits of the stop output byte: 



1 

I 

j 

» 

! ! ! 


! 

! 

? 

t 

t 

t 

! 

t 

ft - - 
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! 

f 

t 
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Not all hardware supports all of these baud rates, and not all 
allows the dynamic changing of baud rates. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file. 

EBARG 

An argument to the system call is invalid. 

ENTTY 

The file referenced by <file_des> is not a character device 


SEE ALSO 
ttyget 
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unlink 


Remove a link to a file. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sys unlink, <file_name> 

Arguments 

<file_name> The address of the null-terminated name to 
unlink. 


DESCRIPTION 

The "unlink" system call removes the entry specified by <file_name> from 
its parent directory. If that entry was the only one on the system that 
referenced the file (i.e., the link count is 0 after the link is 
removed) and the file is closed, the operating system deletes the file. 
If the system call removes the last link to an open file, the operating 
system postpones deleting the file until it is closed. 

The current effective user must have write permission in the directory 
containing the specified file. 


ERRORS REPORTED 
EMSDR 

The path to <file_name> cannot be followed. 

ENDR 

A part of the path to <file_name> is not a directory. 

ENOFL 

No file on the system corresponds to the specified name. 

EPRM 

The directory containing the specified file does not grant write 
permission to the current effective user. 

SEE ALSO 
1 ink 

Commands: diskrepair 
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unmnt 


Unmount the medium in a device. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 

sy s unmnt , <dev_name> 

Arguments 

<dev_name> The address of the null-terminated name of the 
device containing the medium to unmount. The 
specified device must be a block device. 

DESCRIPTION 

The "unmnt" system call unmounts the medium in the specified block 
device from a node of the directory tree. If the indicator that the 
medium is mounted for reading and writing is set, the "unmilt" system 
call clears it. 

Only the system manager may invoke this system call. 


NOTES 

. A medium that was mounted for reading and writing but was not 
unmounted correctly cannot be mounted again until it has been 
repaired by the "diskrepair 11 command. 


ERRORS REPORTED 
EBDEV 

The argument <dev_name> does not reference a device. 

EBSY 

A file on the medium in the specified device is currently open or a 
task has a directory on the medium as its working directory. 

EMSDR 

The path to <file__name> cannot be followed. 

ENMNT 

The medium in the specified device is not mounted. 
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ENOFL 

No file on the system corresponds to the specified name 
EPRM 

Only the system manager may invoke this system call. 


SEE ALSO 
mount 

Commands: diskrepair 
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update 


Update all disks on the system. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys update 


DESCRIPTION 

The "update" system call writes all data in memory that are destined for 
a disk to the appropriate disk. 
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urec 

Remove an entry from the operating system's lock table. 


ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 
sys urec 
Arguments 

<file_des> The file descriptor for the file containing the 
record to unlock. 

DESCRIPTION 

The "urec" system call removes from the operating system's lock table 
the current task's entry for the open file referenced by <file_des>. 

The operating system removes all entries a task makes in the lock table 
when the task terminates. 


ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file, or it 
references a pipe, a character device, a block device, or a 
pseudoterminal. 

EBARG 

An argument to the system call is invalid. 


SEE ALSO 
lrec 
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vfork 


Create a new task. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys vfork 
Returns 

To parent task: <child__task' s__ID> in DO 
To child task: 0 in DO 

Arguments 

<child__task's__ID> The task ID assigned to the child task. 


DESCRIPTION 

The "vfork 11 system call creates a new task (the child task) that is a 
copy of the current task (the parent task). This system call, which is 
available only on systems with virtual memory, is more efficient than 
the "fork" system call because the child task shares the parent task's 
user-accessible memory. After invoking "vfork", the parent task sleeps 
until the child task either terminates or invokes the "exec" or "exece" 
system call. 

The child task has the same priority, user ID, effective user-ID, 
controlling terminal information, default permissions-mask, working 
directory, signal handling set-up, profiling information, and 
user-accessible memory as the parent task. However, it differs from the 
parent task in the following ways: its task ID is different; its parent 
task-ID is the task ID of the parent task; its file descriptors are the 
same, but they are located in a different place in memory; its system 
and user CPU times are set to 0. The child task may neither change the 
size of its memory nor invoke the "memman" , "fork", or "vfork" system 
call. 

The operating system prevents the parent task from executing until the 
child task executes an "exec" or an "exece" system call or until the 
child task terminates. The parent task then resumes execution 2 bytes 
after the "vfork" call. Obviously, then, the first instruction in the 
new task must be a short branch (requiring only 2 bytes). Each task 
determines where to resume by looking at the contents of the DO register 
immediately after execution of the "vfork" call. 
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NOTES 

. The user should make sure that the child task does not alter the 
stack frame in any way or change data that the parent does not 
expect to change. . If invoked on a system that does not have 
virtual memory, the "vfork" system call behaves like the "fork" 
system call. 

ERRORS REPORTED 
ETMTS 

Either the maximum number of tasks allowed to a user or the maximum 
number of tasks allowed to the operating system has been reached. 
The system manager can alter either or both of these limits with the 
"tune" command up to the system-dependent maxima. 

EVFORK 

The current task shares its memory with its parent and may not 
invoke this system call. 


SEE ALSO 
fork 
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wait 

Suspend the task until a child task terminates. 

ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys wait 
Returns 

<task_ID> in DO 
<term__status> in AO 

Arguments 

<task_ID> The task ID of the terminated child task. 

<term__status> The termination status of the terminated child 
task. If the "term" system call terminated 
the task, the upper byte of the word is 0, and 
the lower byte has the value that was in the 
DO register when ’’term" was invoked (i.e., the 
termination status set by "term"). If the 
system terminated the child task abnormally, 
the upper byte is nonzero. The low-order 7 
bits of this byte contain the number of the 
signal that terminated the task. The 
high-order bit is 1 if the system produced a 
core dump; 0, if it did not. The value of the 
lower byte is unpredictable. 

DESCRIPTION 

The "wait" system call suspends the task until a child task terminates. 
If more than one child task has terminated at the time the task invokes 
the system call, the user cannot determine ahead of time to which task 
the values returned refer. 


ERRORS REPORTED 
ENCHD 

No child tasks are active. 

EINTR 

The task caught an interrupt which caused this system -call to 
terminate abnormally . 
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SEE ALSO 
cpint 
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write 

Write data to an open file. 

ASSEMBLY LANGUAGE SYNTAX 
Expected 

<file_des> in DO 
Syntax Statement 

sys write, <buf_add> ,<count> 

Returns 

<by tes_written> 

Arguments 

<file_des> The address of the null-terminated name of 

the file to which to write. 

<buf_add> The address of the buffer containing the 

data to write. 

<count> The number of bytes of data to write from 

the buffer to the file. 

<bytes__written> The number of bytes of data actually written 

to the file. 


DESCRIPTION 

The "write" system call writes data from the buffer at <buf_add> to the 
file referenced by <f ile__des>. It writes at most <count> bytes of data. 
The system call may write less data than requested if it is writing to a 
slow device, such as a terminal, and the task catches an interrupt. 

The "write" system call is most efficient when both <buf__add> and 
<count> are multiples of 512. 

ERRORS REPORTED 
EBADF 

The file descriptor does not reference an open file. 

EBARG 

An argument to the system call is invalid. 
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EDFUL 

The device containing the specified file is full. 

EINTR 

The task caught an interrupt, which caused the system call to end 
abnorma 1 ly . 

EIO 

The operating system returned an I/O error. 

EPIPE 

The system call attempted to write to a broken pipe (a pipe whose 
file descriptor for reading is closed. 

SEE ALSO 
read 
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yield_CPU 

Yield the CPU to another task of equal priority. 


ASSEMBLY LANGUAGE SYNTAX 
Syntax Statement 
sys y ield__CPU 


DESCRIPTION 

The "yield^CPU 11 system call yields the central processing unit (CPU) to 
another task of equal priority if such a task is waiting to execute. 
The ability to yield the CPU is especially important for real-time tasks 
but may also be of some use to non-real-time tasks. 

Normally, the operating system lowers the priority of a non-real-time 
task as time passes so that all tasks can have more or less equal access 
to the system's resources. The system does, however, increase the 
priority of a task that has been suspended. For instance, if a task 
requests information from a file and the operating system must fetch 
that information from a disk, the system suspends the task until the 
information is transferred from the disk to memory. Once the 
information is available, the operating system wakes the task and 
increases its priority. A task that performs many I/O operations may 
take over the system as its priority is repeatedly increased unless it 
deliberately surrenders the CPU with the "y ield___CPU n system call. 

Real-time tasks have fixed priorities, and any real-time task has a 
higher priority than any non-real-time task. Therefore, unless a 
real-time task requests a service from the operating system which causes 
the system to put the task to sleep, the task can continue to execute 
until a real-time task of higher priority usurps the CPU. The 
"yield^CPU" system call allows two or more real-time tasks with the same 
priority to share the CPU. 


NOTES 

. If a task tries to execute when the CPU is in use by a task of equal 
or higher priority, the operating system places the task at the end 
of a queue of tasks of equal priority. When a task yields the CPU, 
the operating system places that task at the end of the queue of 
tasks of the same priority and executes the first task in that 
queue. Thus, if no tasks of equal priority are in the queue when 
the task invokes M y ield_CPU", the system call has no obvious effect. 
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SEE ALSO 

make realtime 
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